onstomp 1.0.0pre1 → 1.0.0

data/lib/onstomp/failover/client.rb

@@ -0,0 +1,127 @@
+# -*- encoding: utf-8 -*-
+
+# A failover client that wraps multiple {OnStomp::Client clients} and maintains
+# a connection to one of these clients. Frames are sent to the currently
+# connected client. If the connection is lost, a failover client will
+# automatically reconnect to another client in the pool, re-transmit any
+# necessary frames and resume operation.
+class OnStomp::Failover::Client
+  include OnStomp::Failover::FailoverConfigurable
+  include OnStomp::Failover::FailoverEvents
+  include OnStomp::Interfaces::FrameMethods
+  
+  # The class to use when instantiating a new {#client_pool}.
+  # Defaults to {OnStomp::Failover::Pools::RoundRobin}
+  # @return [Class]
+  attr_configurable_pool :pool
+  # The class to use when instantiating a new frame buffer.
+  # Defaults to {OnStomp::Failover::Buffers::Written}
+  # @return [Class]
+  attr_configurable_buffer :buffer
+  # The delay in seconds to wait between connection retries.
+  # Defaults to +10+.
+  # @return [Fixnum]
+  attr_configurable_int :retry_delay, :default => 10
+  # The maximum number of times to retry connecting during a reconnect
+  # loop. A non-positive number will force the failover client to try to
+  # reconnect indefinitely. Defaults to +0+
+  # @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+
+  # @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
+    @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
+  # {OnStomp::Client#connected? connected}.
+  # @return [true,false,nil]
+  def connected?
+    active_client && active_client.connected?
+  end
+
+  # Transmits a frame to the {#active_client} if one exists.
+  # @return [OnStomp::Components::Frame,nil]
+  def transmit frame, cbs={}
+    active_client && active_client.transmit(frame, cbs)
+  end
+  
+  # Connects to one of the clients in the {#client_pool}
+  # @return [self]
+  def connect
+    @disconnecting = false
+    unless reconnect
+      raise OnStomp::Failover::MaximumRetriesExceededError
+    end
+    self
+  end
+  
+  # Ensures that a connection is properly established, then invokes
+  # {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
+  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.
+          active_client.connect # <--- From here
+          @connection = active_client.connection
+        rescue Exception
+          trigger_failover_event :connect_failure, :on, active_client, $!.message
+        end
+        trigger_failover_retry :after, attempt
+        attempt += 1
+      end
+      connected?.tap do |b|
+        b && trigger_failover_event(:connected, :on, active_client)
+        @client_ready = b
+      end # <--- Until here
+    end
+  end
+  
+  def retry_exceeded? attempt
+    retry_attempts > 0 && attempt > retry_attempts
+  end
+  
+  def sleep_for_retry attempt
+    sleep(retry_delay) if retry_delay > 0 && attempt > 1
+  end
+    
+  def create_client_pool
+    @client_pool = pool.new(uri.failover_uris)
+    on_connection_closed do |client, *_|
+      unless @disconnecting
+        trigger_failover_event(:lost, :on, active_client)
+        reconnect
+      end
+    end
+  end
+end

data/lib/onstomp/failover/failover_configurable.rb

@@ -0,0 +1,63 @@
+# -*- encoding: utf-8 -*-
+
+# Module for configurable attributes specific to
+# {OnStomp::Failover::Client failover} clients.
+module OnStomp::Failover::FailoverConfigurable
+  # Includes {OnStomp::Interfaces::ClientConfigurable} into +base+ and
+  # extends {OnStomp::Failover::FailoverConfigurable::ClassMethods}
+  # @param [Module] base
+  def self.included(base)
+    base.__send__ :include, OnStomp::Interfaces::ClientConfigurable
+    base.extend ClassMethods
+  end
+  
+  # Provides attribute methods for {OnStomp::Failover::Client failover}
+  # clients.
+  module ClassMethods
+    # Creates readable and writeable attributes that are automatically
+    # converted into integers.
+    def attr_configurable_int *args, &block
+      trans = attr_configurable_wrap lambda { |v| v.to_i }, block
+      attr_configurable_single(*args, &trans)
+    end
+    
+    # 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
+    # the reader methods with +attr_name?+
+    def attr_configurable_bool *args, &block
+      trans = attr_configurable_wrap lambda { |v|
+        [true, 'true', '1', 1].include?(v) }, block
+      attr_configurable_single(*args, &trans)
+      args.each do |a|
+        unless a.is_a?(Hash)
+          alias_method :"#{a}?", a
+        end
+      end
+    end
+    
+    # Creates a readable and writeable attribute with the given name that
+    # defaults to the {OnStomp::Failover::Pools::RoundRobin}. Corresponds
+    # the the class to use when creating new
+    # {OnStomp::Failover::Client#client_pool client pools}.
+    # @param [Symbol] nm name of attribute
+    def attr_configurable_pool nm
+      attr_configurable_class(nm,
+        :default => OnStomp::Failover::Pools::RoundRobin) do |p|
+        p || OnStomp::Failover::Pools::RoundRobin
+      end
+    end
+    
+    # Creates a readable and writeable attribute with the given name that
+    # defaults to the {OnStomp::Failover::Buffers::Written}. Corresponds
+    # the the class to use for frame buffering and de-buffering.
+    # @param [Symbol] nm name of attribute
+    def attr_configurable_buffer nm
+      attr_configurable_class(nm,
+        :default => OnStomp::Failover::Buffers::Written) do |b|
+        b || OnStomp::Failover::Buffers::Written
+      end
+    end
+  end
+end

data/lib/onstomp/failover/failover_events.rb

@@ -0,0 +1,96 @@
+# -*- encoding: utf-8 -*-
+
+# Events mixin for {OnStomp::Failover::Client failover} clients.
+module OnStomp::Failover::FailoverEvents
+  include OnStomp::Interfaces::EventManager
+  
+  # We do this one using +class << self+ instead of the +self.included+ hook
+  # because we need 'create_client_event_method+ immediately.
+  class << self
+    # Creates a forwarded binding for client events.
+    def create_client_event_method name
+      module_eval "def #{name}(&block); bind_client_event(:#{name}, block); end"
+    end
+  end
+  
+  # Create forwarded bindings for all {OnStomp::Client} events.
+  OnStomp::Interfaces::ClientEvents.event_methods.each do |ev|
+    create_client_event_method ev
+  end
+  
+  # Binds a callback to {OnStomp::Client#on_connction_established}. This has
+  # to be handled directly because :on_connection_established isn't a true
+  # event.
+  def on_connection_established &block
+    bind_client_event(:on_connection_established, block)
+  end
+  # Binds a callback to {OnStomp::Client#on_connection_died}. This has
+  # to be handled directly because :on_connection_died isn't a true
+  # event.
+  def on_connection_died &block
+    bind_client_event(:on_connection_died, block)
+  end
+  # Binds a callback to {OnStomp::Client#on_connection_terminated}. This has
+  # to be handled directly because :on_connection_terminated isn't a true
+  # event.
+  def on_connection_terminated &block
+    bind_client_event(:on_connection_terminated, block)
+  end
+  # Binds a callback to {OnStomp::Client#on_connection_closed}. This has
+  # to be handled directly because :on_connection_closed isn't a true
+  # event.
+  def on_connection_closed &block
+    bind_client_event(:on_connection_closed, block)
+  end
+  
+  # Sets up a forwarded event binding, applying it to all clients in 
+  # {OnStomp::Failover::Client#client_pool}.
+  def bind_client_event(name, block)
+    client_pool.each do |client|
+      client.__send__ name do |*args|
+        if client == active_client
+          block.call *args
+        end
+      end
+    end
+  end
+  
+  # Binds a callback to be invoked when a failover client is attempting to
+  # connect through a new {OnStomp::Client client} in its
+  # {OnStomp::Failover::Client#pool}.
+  # @yield [failover, attempt, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Failover::Client] failover
+  # @yieldparam [Fixnum] attempt
+  # @yieldparam [OnStomp::Client] client
+  create_event_methods :failover_retry, :before, :after
+  # Binds a callback to be invoked when a failover client fails to establish
+  # a connection through a {OnStomp::Client client} while reconnecting.
+  # @yield [failover, client, error_message] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Failover::Client] failover
+  # @yieldparam [OnStomp::Client] client
+  # @yieldparam [String] error_message
+  create_event_methods :failover_connect_failure, :on
+  #create_event_methods :failover_retries_exceeded, :on
+  # Binds a callback to be invoked when an established connection through a
+  # client is lost.
+  # @yield [failover, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Failover::Client] failover
+  # @yieldparam [OnStomp::Client] client
+  create_event_methods :failover_lost, :on
+  # Binds a callback to be invoked when a connection through a
+  # client is established.
+  # @yield [failover, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Failover::Client] failover
+  # @yieldparam [OnStomp::Client] client
+  create_event_methods :failover_connected, :on
+  
+  # Triggers a failover retry event
+  def trigger_failover_retry pref, attempt
+    trigger_failover_event :retry, pref, attempt, self.active_client
+  end
+  
+  # Triggers a general failover event
+  def trigger_failover_event ev, pref, *args
+    trigger_event :"#{pref}_failover_#{ev}", self, *args
+  end
+end

data/lib/onstomp/failover/new_with_failover.rb

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+
+class OnStomp::Client
+  class << self
+    # Creates an alias chain for {OnStomp::Client.new} so that if
+    # a failover: URI or an array of URIs are passed to the constructor,
+    # a {OnStomp::Failover::Client failover} client is built instead.
+    # @return [OnStomp::Client,OnStomp::Failover::Client]
+    def new_with_failover(uri, options={})
+      if uri.is_a?(Array) || uri.to_s =~ /^failover:/i
+        OnStomp::Failover::Client.new(uri, options)
+      else
+        new_without_failover(uri, options)
+      end
+    end
+    
+    alias :new_without_failover :new
+    alias :new :new_with_failover
+  end
+end

data/lib/onstomp/failover/pools.rb

@@ -0,0 +1,8 @@
+# -*- encoding: utf-8 -*-
+
+# Namespace for client pool managers.
+module OnStomp::Failover::Pools
+end
+
+require 'onstomp/failover/pools/base'
+require 'onstomp/failover/pools/round_robin'

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

@@ -0,0 +1,39 @@
+# -*- encoding: utf-8 -*-
+
+# 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.
+class OnStomp::Failover::Pools::Base
+  attr_reader :clients
+  
+  # Creates a new client pool by mapping an array of URIs into an array of
+  # {OnStomp::Client clients}.
+  def initialize uris
+    @clients = uris.map do |u|
+      OnStomp::Client.new u
+    end
+  end
+  
+  # Raises an error, because it is up to subclasses to define this behavior.
+  # @raise [StandardError]
+  def next_client
+    raise 'implemented in subclasses'
+  end
+  
+  # Shuffles the client pool.
+  def shuffle!
+    clients.shuffle!
+  end
+  
+  # Yields each client in the pool to the supplied block. Raises an error
+  # if no block is provided.
+  # @raise [ArgumentError] if no block is given
+  # @yield [client] block to call for each client in the pool
+  # @yieldparam [OnStomp::Client] client
+  # @return [self]
+  def each &block
+    raise ArgumentError, 'no block provided' unless block_given?
+    clients.each &block
+    self
+  end
+end

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

@@ -0,0 +1,17 @@
+# -*- encoding: utf-8 -*-
+
+# A round-robin client pool. Clients are processed sequentially, and once
+# all clients have been processed, the pool cycles back to the beginning.
+class OnStomp::Failover::Pools::RoundRobin < OnStomp::Failover::Pools::Base
+  def initialize uris
+    super
+    @index = -1
+  end
+
+  # Returns the next sequential client in the pool
+  # @return [OnStomp::Client]
+  def next_client
+    @index = (@index + 1) % clients.size
+    clients[@index]
+  end
+end

data/lib/onstomp/failover/uri.rb

@@ -0,0 +1,34 @@
+# -*- encoding: utf-8 -*-
+
+# Namespace for failover related URI classes.
+module OnStomp::Failover::URI
+  # A URI class for representing URIs with a 'failover' scheme.
+  class FAILOVER < OnStomp::Components::URI::STOMP
+    # Matches the internal URIs and query contained in
+    # the +opaque+ part of a failover: URI
+    FAILOVER_OPAQUE_REG = /^\(([^\)]+)\)(?:\?(.*))?/
+    
+    attr_reader :failover_uris
+    def initialize(*args)
+      super
+      _split_opaque_
+    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
+      end
+    end
+  end
+end
+
+module ::URI
+  @@schemes['FAILOVER'] = OnStomp::Failover::URI::FAILOVER
+end

data/lib/onstomp/interfaces/client_configurable.rb

@@ -40,16 +40,12 @@ module OnStomp::Interfaces::ClientConfigurable
     end
     
     # Creates a readable and writeable attribute with the given name that
-    # defaults to the {OnStomp::Components::ThreadedProcessor} and if set
-    # to nil will instead use {OnStomp::Components::NilProcessor}. Corresponds
+    # defaults to the {OnStomp::Components::ThreadedProcessor}. Corresponds
     # the the class to use when create new processor instances when a client
     # is connected.
     # @param [Symbol] nm name of attribute
     def attr_configurable_processor nm
-      attr_configurable_class(nm,
-        :default => OnStomp::Components::ThreadedProcessor) do |pr|
-        pr || OnStomp::Components::NilProcessor
-      end
+      attr_configurable_class(nm, :default => OnStomp::Components::ThreadedProcessor)
     end
   end
 end

data/lib/onstomp/interfaces/client_events.rb

@@ -12,6 +12,10 @@ module OnStomp::Interfaces::ClientEvents
 
   # @group Client Frame Event Bindings
   
+  # Can't get +before+ because the CONNECT frame isn't transmitted by
+  # the client.
+  create_event_methods :connect, :on
+  
   # 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

data/lib/onstomp/interfaces/connection_events.rb

@@ -42,8 +42,8 @@ module OnStomp::Interfaces::ConnectionEvents
 
   # Triggers a connection specific event.
   # @param [Symbol] event name
-  def trigger_connection_event event
-    trigger_event :"on_#{event}", self.client, self
+  def trigger_connection_event event, msg=''
+    trigger_event :"on_#{event}", self.client, self, msg
   end
   
   # Takes a hash of event bindings a {OnStomp::Client client} has stored
@@ -57,6 +57,6 @@ module OnStomp::Interfaces::ConnectionEvents
     ev_hash.each do |ev, cbs|
       cbs.each { |cb| bind_event(ev, cb) }
     end
-    trigger_connection_event :established
+    trigger_connection_event :established, "STOMP #{self.version} connection negotiated"
   end
 end