isimud 0.7.0 → 1.3.1

data/isimud.gemspec

@@ -4,28 +4,30 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'isimud/version'
 
 Gem::Specification.new do |spec|
-  spec.name        = 'isimud'
-  spec.version     = Isimud::VERSION
-  spec.authors     = ['George Feil', 'Brian Jenkins']
-  spec.email       = %w{george.feil@keas.com bonkydog@bonkydog.com}
-  spec.summary     = %q{AMQP Messaging and Event Processing}
-  spec.description = <<-EOT
-Isimud is an AMQP message publishing and consumption gem intended for Rails applications. You can use it to define
-message consumption queues for ActiveRecord instances, or synchronize model updates between processes. It also provides
-an event listener background process for managing queues that consume messages.
-  EOT
-  spec.homepage    = 'https://github.com/KeasInc/isimud'
-  spec.license     = 'MITNFA'
-  spec.cert_chain  = ['certs/gfeil.pem']
-  spec.signing_key = File.expand_path("~/.ssh/gem-private_key.pem") if $0 =~ /gem\z/
+  spec.name          = 'isimud'
+  spec.version       = Isimud::VERSION
+  spec.authors       = ['George Feil', 'Brian Jenkins']
+  spec.email         = %w{george.feil@keas.com bonkydog@bonkydog.com}
+  spec.summary       = %q{AMQP Messaging and Event Processing}
+  spec.description   = <<-EOT
+Isimud is an AMQP message publishing and consumption gem that is intended for managing asynchronous event queues in Rails applications. It consists of the following components:
+
+* A [Bunny](http://rubybunny.info) based client interface for publishing and receiving messages using AMQP.
+* A test client which mocks most client operations and allows for synchronous delivery and processing of messages for unit tests.
+* A Model Watcher mixin for ActiveRecord that automatically sends messages whenever an ActiveRecord instance is created, modified, or destroyed.
+* An Event Observer mixin for registering ActiveRecord models and instances with the EventListener for receiving messages.
+* An Event Listener daemon process which manages queues and dispatches messages for Event Observers.
+EOT
+  spec.homepage      = 'https://github.com/KeasInc/isimud'
+  spec.license       = 'MITNFA'
 
   spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'activerecord', '>= 3.2.17'
-  spec.add_dependency 'activesupport', '>= 3.2.17'
+  spec.add_dependency 'activerecord', '>= 4.1.4'
+  spec.add_dependency 'activesupport', '>= 4.1.4'
   spec.add_dependency 'bunny', '>= 1.6.0'
   spec.add_dependency 'chronic_duration', '>= 0.10.6'
 end

data/lib/isimud/bunny_client.rb

@@ -2,64 +2,96 @@ require 'bunny'
 require 'logger'
 
 module Isimud
+
+  # Interface for Bunny RabbitMQ client
+  # @see http://rubybunny.info
   class BunnyClient < Isimud::Client
     DEFAULT_URL = 'amqp://guest:guest@localhost'
 
     attr_reader :url
 
+    # Initialize a new BunnyClient instance. Note that a connection is not established until any other method is called
+    #
+    # @param [String, Hash] _url Server URL or options hash
+    # @param [Hash] _bunny_options optional Bunny connection options
+    # @see Bunny.new for connection options
     def initialize(_url = nil, _bunny_options = {})
       log "Isimud::BunnyClient.initialize: options = #{_bunny_options.inspect}"
       @url           = _url || DEFAULT_URL
       @bunny_options = _bunny_options
     end
 
+    # Convenience method that finds or creates a named queue, binds to an exchange, and subscribes to messages.
+    # If a block is provided, it will be called by the consumer each time a message is received.
+    #
+    # @param [String] queue_name name of the queue
+    # @param [String] exchange_name name of the AMQP exchange. Note that existing exchanges must be declared as Topic
+    #   exchanges; otherwise, an error will occur
+    # @param [Array<String>] routing_keys list of routing keys to be bound to the queue for the specified exchange.
+    # @yieldparam [String] payload message text
+    # @return [Bunny::Consumer] Bunny consumer interface
     def bind(queue_name, exchange_name, *routing_keys, &block)
-      create_queue(queue_name, exchange_name,
-                   queue_options:     {durable: true},
-                   routing_keys:      routing_keys,
-                   subscribe_options: {manual_ack: true}, &block)
+      queue = create_queue(queue_name, exchange_name,
+                           queue_options: {durable: true},
+                           routing_keys:  routing_keys)
+      subscribe(queue, &block) if block_given?
+    end
+
+    # Find or create a named queue and bind it to the specified exchange
+    #
+    # @param [String] queue_name name of the queue
+    # @param [String] exchange_name name of the AMQP exchange. Note that pre-existing exchanges must be declared as Topic
+    #   exchanges; otherwise, an error will occur
+    # @param [Hash] options queue declaration options
+    # @option options [Boolean] :queue_options ({durable: true}) queue declaration options -- @see Bunny::Channel#queue
+    # @option options [Array<String>] :routing_keys ([]) routing keys to be bound to the queue. Use "*" to match any 1 word
+    #   in a route segment. Use "#" to match 0 or more words in a segment.
+    # @return [Bunny::Queue] Bunny queue
+    def create_queue(queue_name, exchange_name, options = {})
+      queue_options = options[:queue_options] || {durable: true}
+      routing_keys  = options[:routing_keys] || []
+      log "Isimud::BunnyClient: create_queue #{queue_name}: queue_options=#{queue_options.inspect}"
+      queue = find_queue(queue_name, queue_options)
+      bind_routing_keys(queue, exchange_name, routing_keys) if routing_keys.any?
+      queue
     end
 
-    def create_queue(queue_name, exchange_name, options = {}, &block)
-      queue_options     = options[:queue_options] || {}
-      routing_keys      = options[:routing_keys] || []
-      subscribe_options = options[:subscribe_options] || {}
-      log "Isimud: create_queue #{queue_name}: queue_options=#{queue_options.inspect} routing_keys=#{routing_keys.join(',')} subscribe_options=#{subscribe_options.inspect}"
+    # Subscribe to messages on the Bunny queue. The provided block will be called each time a message is received.
+    #   The message will be acknowledged and deleted from the queue unless an exception is raised from the block.
+    #   In the case that an exception is caught, the message is rejected, and any declared exception handlers will
+    #   be called.
+    #
+    # @param [Bunny::Queue] queue Bunny queue
+    # @param [Hash] options {manual_ack: true} subscription options -- @see Bunny::Queue#subscribe
+    # @yieldparam [String] payload message text
+    def subscribe(queue, options = {manual_ack: true}, &block)
       current_channel = channel
-      queue           = find_queue(queue_name, queue_options)
-      bind_routing_keys(queue, exchange_name, routing_keys)
-      queue.subscribe(subscribe_options) do |delivery_info, properties, payload|
+      queue.subscribe(options) do |delivery_info, properties, payload|
         begin
-          log "Isimud: queue #{queue_name} received #{delivery_info.delivery_tag} routing_key: #{delivery_info.routing_key}"
-          Thread.current['isimud_queue_name']    = queue_name
+          log "Isimud: queue #{queue.name} received #{delivery_info.delivery_tag} routing_key: #{delivery_info.routing_key}"
+          Thread.current['isimud_queue_name']    = queue.name
           Thread.current['isimud_delivery_info'] = delivery_info
           Thread.current['isimud_properties']    = properties
           block.call(payload)
-          log "Isimud: queue #{queue_name} finished with #{delivery_info.delivery_tag}, acknowledging"
+          log "Isimud: queue #{queue.name} finished with #{delivery_info.delivery_tag}, acknowledging"
           current_channel.ack(delivery_info.delivery_tag)
         rescue => e
-          log("Isimud: queue #{queue_name} error processing #{delivery_info.delivery_tag} payload #{payload.inspect}: #{e.class.name} #{e.message}\n  #{e.backtrace.join("\n  ")}", :warn)
+          log("Isimud: queue #{queue.name} error processing #{delivery_info.delivery_tag} payload #{payload.inspect}: #{e.class.name} #{e.message}\n  #{e.backtrace.join("\n  ")}", :warn)
           current_channel.reject(delivery_info.delivery_tag, Isimud.retry_failures)
-          exception_handler.try(:call, e)
+          run_exception_handlers(e)
         end
       end
-      queue
-    end
-
-    # replace all bindings on a queue
-    def rebind(queue_name, exchange_name, routing_keys)
-      log "Isimud: rebinding queue #{queue_name} exchange #{exchange_name} routing_keys #{routing_keys.inspect}"
-      queue = find_queue(queue_name)
-      queue.unbind(exchange_name)
-      bind_routing_keys(queue, exchange_name, routing_keys)
-    rescue => e
-      log "Isimud: error rebinding #{queue_name} from #{exchange_name}: #{e.message}", :error
     end
 
+    # Permanently delete the queue from the AMQP server. Any messages present in the queue will be discarded.
+    # @param [String] queue_name queue name
+    # @return [AMQ::Protocol::Queue::DeleteOk] RabbitMQ response
     def delete_queue(queue_name)
       channel.queue_delete(queue_name)
     end
 
+    # Establish a connection to the AMQP server, or return the current connection if one already exists
+    # @return [Bunny::Session]
     def connection
       @connection ||= ::Bunny.new(url, @bunny_options).tap(&:start)
     end
@@ -68,6 +100,10 @@ module Isimud
 
     CHANNEL_KEY = :'isimud.bunny_client.channel'
 
+    # Open a new, thread-specific AMQP connection channel, or return the current channel for this thread if it exists
+    #   and is currently open. New channels are created with publisher confirms enabled. Messages will be prefetched
+    #   according to Isimud.prefetch_count when declared.
+    # @return [Bunny::Channel] channel instance.
     def channel
       if (channel = Thread.current[CHANNEL_KEY]).try(:open?)
         channel
@@ -79,36 +115,53 @@ module Isimud
       end
     end
 
+    # Reset this client by closing all channels for the connection.
     def reset
       connection.close_all_channels
     end
 
+    # Determine if a Bunny connection is currently established to the AMQP server.
+    # @return [Boolean,nil] true if a connection was established and is active or starting, false if a connection exists
+    # but is closed or closing, or nil if no connection has been established.
     def connected?
       @connection && @connection.open?
     end
 
+    # Close the AMQP connection and clear it from the instance.
+    # @return nil
     def close
       connection.close
     ensure
       @connection = nil
     end
 
-    def publish(exchange, routing_key, payload, options = {})
-      channel.topic(exchange, durable: true).publish(payload, options.merge(routing_key: routing_key, persistent: true))
+    # Publish a message to the specified exchange, which is declared as a durable, topic exchange. Note that message
+    #   is always persisted.
+    # @param [String] exchange AMQP exchange name
+    # @param [String] routing_key message routing key. This should always be in the form of words separated by dots
+    #   e.g. "user.goal.complete"
+    # @see http://rubybunny.info/articles/exchanges.html
+    def publish(exchange, routing_key, payload)
+      channel.topic(exchange, durable: true).publish(payload, routing_key: routing_key, persistent: true)
     end
 
+    # Close and reopen the AMQP connection
+    # @return [Bunny::Session]
     def reconnect
       close
       connect
     end
 
-    private
-
+    # Look up a queue by name, or create it if it does not already exist.
     def find_queue(queue_name, options = {durable: true})
       channel.queue(queue_name, options)
     end
 
+    private
+
     def bind_routing_keys(queue, exchange_name, routing_keys)
+      log "Isimud::BunnyClient: bind queue #{queue.name} exchange #{exchange_name} routing_keys: #{routing_keys.join(',')}"
+      channel.exchange(exchange_name, type: :topic, durable: true)
       routing_keys.each { |key| queue.bind(exchange_name, routing_key: key, nowait: false) }
     end
 

data/lib/isimud/client.rb

@@ -3,8 +3,6 @@ module Isimud
   class Client
     include Isimud::Logging
 
-    attr_reader :exception_handler
-
     def initialize(server = nil, options = nil)
     end
 
@@ -23,27 +21,45 @@ module Isimud
     def connected?
     end
 
-    def create_queue(queue_name, exchange_name, options = {}, &method)
+    def create_queue(queue_name, exchange_name, options = {})
     end
 
     def delete_queue(queue_name)
     end
 
+    def find_queue(queue_name, options = {})
+    end
+
+    # Declare a proc to be run whenever an uncaught exception is raised within a message processing block.
+    # This is useful for logging or monitoring errors, for instance.
+    # @yieldparam [Exception] e exception raised
     def on_exception(&block)
-      @exception_handler = block
+      exception_handlers << block
     end
 
-    def publish(exchange, routing_key, payload, options = {})
+    # Call each of the exception handlers declared by #on_exception.
+    # @param [Exception] exception
+    def run_exception_handlers(exception)
+      exception_handlers.each{|handler| handler.call(exception)}
     end
 
-    def reconnect
+    def publish(exchange, routing_key, payload)
     end
 
-    def rebind(queue_name, exchange_name, *keys)
+    def reconnect
     end
 
     def reset
     end
+
+    def subscribe(queue, options = {}, &block)
+    end
+
+    private
+
+    def exception_handlers
+      @exception_handlers ||= Array.new
+    end
   end
 end
 

data/lib/isimud/event.rb

@@ -1,15 +1,19 @@
 require 'active_support'
 
 module Isimud
+  # A structured message format useful for processing events.
+  # Note that each message has a routing key automatically constructed based on four properties:
+  # type.eventful_type.eventful_id.action
+  # Any blank or nil properties are omitted from the routing key.
+  # For convenience, you may construct an event using an eventful object, which sets the eventful_type and eventful_id
   class Event
     include Isimud::Logging
     attr_accessor :type, :action, :user_id, :occurred_at, :eventful_type, :eventful_id, :attributes, :parameters
-    attr_reader :timestamp
     attr_writer :exchange
 
     DEFAULT_TYPE = :model
 
-    # Initialize a new Event
+    # Initialize a new Event.
     # @overload new(user, eventful, attributes)
     #   @param[#id] user user associated by the event
     #   @param[ActiveRecord::Base] eventful object associated with event
@@ -17,12 +21,13 @@ module Isimud
     # @overload new(attributes)
     #   @param[Hash] attributes event attributes
     #   @option attributes [Integer] :user_id ID of User associated with event
-    #   @option attributes [String] :eventful_type class of object associated with event
+    #   @option attributes [String] :eventful_type type of object associated with event
     #   @option attributes [Integer] :eventful_id id of object associated with event
     #   @option attributes [String] :exchange (Isimud.events_exchange) exchange for publishing event
-    #   @option attributes [ActiveRecord::Base] :eventful object associated with event. This sets :eventful_type and :eventful_id.
+    #   @option attributes [#id] :eventful object associated with event. This sets :eventful_type and :eventful_id based
+    #     on the class and ID of the object.
     #   @option attributes [String, Symbol] :type (:model) event type
-    #   @option attributes [String] :action event action
+    #   @option attributes [String, Symbol] :action event action
     #   @option attributes [Time] :occurred_at (Time.now) date and time event occurred
     #   @option attributes [Hash] :attributes event attributes
     #   @option attributes [Hash] :parameters additional parameters (deprecated)
@@ -38,7 +43,6 @@ module Isimud
                          else
                            Time.now.utc
                          end
-      @timestamp       = Time.now
 
       eventful_object = options.delete(:eventful)
 
@@ -69,13 +73,6 @@ module Isimud
       [type.to_s, eventful_type, eventful_id, action].compact.join('.')
     end
 
-    # Message ID, which is generated from the exchange, routing_key, user_id, and timestamp. This is practically
-    # guaranteed to be unique across all publishers.
-    def message_id
-      [exchange, routing_key, user_id, timestamp.to_i, timestamp.nsec].join(':')
-    end
-
-
     # Return hash of data to be serialized to JSON
     # @option options [Boolean] :omit_parameters when set, do not include attributes or parameters in data
     # @return [Hash] data to serialize
@@ -115,7 +112,7 @@ module Isimud
     def publish
       data = self.serialize
       log "Event#publish: #{self.inspect}"
-      Isimud.client.publish(exchange, routing_key, data, message_id: message_id)
+      Isimud.client.publish(exchange, routing_key, data)
     end
   end
 end

data/lib/isimud/event_listener.rb

@@ -2,47 +2,94 @@ require 'isimud'
 require 'thread'
 
 module Isimud
-  class EventListener
+  # Daemon process manager for monitoring event queues.
+  # Known EventObserver models and their instances automatically registered upon startup. It is also possible to
+  # define ad-hoc queues and handlers by extending
+  # In addition, ad-hoc event managing may be set up by extending bind_queues() and making the appropriate subscribe
+  # calls directly.
+  #
+  # =====================================
+  # Threads created by the daemon process
+  # =====================================
+  #
+  # Upon startup, EventListener operates using the following threads:
+  # * An event processing thread that establishes consumers for message queues
+  # * An error counter thread that manages the error counter
+  # * A shutdown thread that listens for INT or TERM signals, which will trigger a graceful shutdown.
+  # * The main thread is put to sleep until a shutdown is required.
+  #
+  # ==================
+  # Registering Queues
+  # ==================
+  #
+  # All active instances of all known EventObserver classes (which are assumed to be ActiveRecord instances) are
+  # automatically loaded by the event processing thread, and their associated queues are bound. Note that queues
+  # and associated routing key bindings are established at the time the instance is created or modified.
+  # @see EventObserver.find_active_observers
+  #
+  # Each EventListener process creates an exclusive queue for monitoring the creation, modification, and destruction
+  # of EventObserver instances, using ModelWatcher messages.
+  #
+  # ==============
+  # Error Handling
+  # ==============
+  #
+  # Whenever an uncaught exception is rescued from a consumer handling a message, it is logged and the error counter
+  # is incremented. The error counter is reset periodically according to the value of +error_interval+.
+  # If the total number of errors logged exceeds +error_limit+, the process is terminated immediately.
+  # @see BunnyClient#subscribe()
+  #
+  # There are certain situations that may cause a Bunny exception to occur, such as a loss of network connection.
+  # Whenever a Bunny exception is rescued in the event processing thread, the Bunny session is closed (canceling all
+  # queue consumers), in addition to the error being counted, all Bunny channels are closed, and queues are
+  # reinitialized.
+class EventListener
     include Logging
+
+    # @!attribute [r] error_count
+    #   @return [Integer] count of errors (uncaught exceptions) that have occurred in the current error interval
+
     attr_reader :error_count, :error_interval, :error_limit, :name, :queues, :events_exchange, :models_exchange,
                 :running
 
-    DEFAULT_ERROR_LIMIT    = 10
-    DEFAULT_ERROR_INTERVAL = 3600
+    DEFAULT_ERROR_LIMIT     = 10
+    DEFAULT_ERROR_INTERVAL  = 3600
 
     DEFAULT_EVENTS_EXCHANGE = 'events'
     DEFAULT_MODELS_EXCHANGE = 'models'
 
+    # Initialize a new EventListener daemon instance
+    # @param [Hash] options daemon options
+    # @option options [Integer] :error_limit (10) maximum number of errors that are allowed to occur within error_interval
+    #   before the process terminates
+    # @option options [Integer] :error_interval (3600) time interval, in seconds, before the error counter is cleared
+    # @option options [String] :events_exchange ('events') name of AMQP exchange used for listening to event messages
+    # @option options [String] :models_exchange ('models') name of AMQP exchange used for listening to EventObserver
+    #   instance create, update, and destroy messages
+    # @option options [String] :name ("#{Rails.application.class.parent_name.downcase}-listener") daemon instance name.
     def initialize(options = {})
       default_options = {
-          error_limit:     Isimud.listener_error_limit || DEFAULT_ERROR_LIMIT,
-          error_interval:  DEFAULT_ERROR_INTERVAL,
-          events_exchange: Isimud.events_exchange || DEFAULT_EVENTS_EXCHANGE,
-          models_exchange: Isimud.model_watcher_exchange || DEFAULT_MODELS_EXCHANGE,
-          name:            "#{Rails.application.class.parent_name.downcase}-listener"
+          error_limit:      Isimud.listener_error_limit || DEFAULT_ERROR_LIMIT,
+          error_interval:   DEFAULT_ERROR_INTERVAL,
+          events_exchange:  Isimud.events_exchange || DEFAULT_EVENTS_EXCHANGE,
+          models_exchange:  Isimud.model_watcher_exchange || DEFAULT_MODELS_EXCHANGE,
+          name:             "#{Rails.application.class.parent_name.downcase}-listener"
       }
       options.reverse_merge!(default_options)
-      @error_count         = 0
-      @observers           = Hash.new
-      @observed_models     = Set.new
-      @error_limit         = options[:error_limit]
-      @error_interval      = options[:error_interval]
-      @events_exchange     = options[:events_exchange]
-      @models_exchange     = options[:models_exchange]
-      @name                = options[:name]
-      @observer_mutex      = Mutex.new
-      @error_counter_mutex = Mutex.new
-      @running             = false
-    end
-
-    def max_errors
-      Isimud.listener_error_limit || DEFAULT_ERROR_LIMIT
-    end
-
-    def test_env?
-      ['cucumber', 'test'].include?(Rails.env)
+      @error_count          = 0
+      @observers            = Hash.new
+      @observed_models      = Set.new
+      @error_limit          = options[:error_limit]
+      @error_interval       = options[:error_interval]
+      @events_exchange      = options[:events_exchange]
+      @models_exchange      = options[:models_exchange]
+      @name                 = options[:name]
+      @observer_mutex       = Mutex.new
+      @error_counter_mutex  = Mutex.new
+      @running              = false
     end
 
+    # Run the daemon process. This creates the event, error counter, and shutdown threads
     def run
       @running = true
       bind_queues and return if test_env?
@@ -60,8 +107,23 @@ module Isimud
       client.close
     end
 
-    # Override this method to set up message observers
+    # Hook for setting up custom queues in your application. Override in your subclass.
+    def bind_event_queues
+    end
+
+    # @private
     def bind_queues
+      bind_observer_queues
+      bind_event_queues
+    end
+
+    private
+
+    def test_env?
+      ['cucumber', 'test'].include?(Rails.env)
+    end
+
+    def bind_observer_queues
       Isimud::EventObserver.observed_models.each do |model_class|
         log "EventListener: registering observers for #{model_class}"
         register_observer_class(model_class)
@@ -72,14 +134,15 @@ module Isimud
         end
         log "EventListener: registered #{count} observers for #{model_class}"
       end
+      client.subscribe(observer_queue) do |payload|
+        handle_observer_event(payload)
+      end
     end
 
     def has_observer?(observer)
       @observers.has_key?(observer_key_for(observer.class, observer.id))
     end
 
-    private
-
     def start_shutdown_thread
       shutdown_thread = Thread.new do
         Thread.stop # wait until we get a TERM or INT signal.
@@ -100,11 +163,12 @@ module Isimud
         while @running
           begin
             bind_queues
-            Rails.logger.info 'EventListener: event_thread finished'
+            log 'EventListener: event_thread finished'
             Thread.stop
           rescue Bunny::Exception => e
             count_error(e)
-            Rails.logger.warn 'EventListener: resetting queues'
+            log 'EventListener: resetting queues', :warn
+            @observer_queue = nil
             client.reset
           end
         end
@@ -123,7 +187,6 @@ module Isimud
       end
     end
 
-    # start an error counter thread that clears the error count once per hour
     def start_error_counter_thread
       log 'EventListener: starting error counter'
       @error_count = 0
@@ -142,55 +205,50 @@ module Isimud
       event = JSON.parse(payload).with_indifferent_access
       action = event[:action]
       log "EventListener: received observer model message: #{event.inspect}"
-      observer = event[:type].constantize.find(event[:id]) unless action == 'destroy'
-      case
-        when action == 'create'
-          register_observer(observer) if observer.enable_listener?
-        when action == 'update' && observer.enable_listener?
-          rebind_observer(observer)
-        else
-          unregister_observer(event[:type], event[:id])
+      if %w(update destroy).include?(action)
+        unregister_observer(event[:type], event[:id])
+      end
+      if %w(create update).include?(action)
+        observer = event[:type].constantize.find(event[:id])
+        register_observer(observer) if observer.enable_listener?
       end
     end
 
-    # Create and bind a queue for the observer. Also ensure that we are listening for observer class update events
-    def register_observer(observer)
+    # Register the observer class watcher
+    def register_observer_class(observer_class)
       @observer_mutex.synchronize do
-        log "EventListener: registering observer #{observer.class} #{observer.id}"
-        observer.observe_events(client, events_exchange)
-        @observers[observer_key_for(observer.class, observer.id)] = observer
+        return if @observed_models.include?(observer_class)
+        @observed_models << observer_class
+        log "EventListener: registering observer class #{observer_class}"
+        observer_queue.bind(models_exchange, routing_key: "#{Isimud.model_watcher_schema}.#{observer_class.base_class.name}.*")
       end
     end
 
-    # Update the bindings for an observer.
-    def rebind_observer(observer)
-      log "EventListener: rebinding observer #{observer.class} #{observer.id}"
-      client.rebind(observer.event_queue_name, events_exchange, observer.routing_keys)
+    # Register an observer instance, and start listening for events on its associated queue.
+    # Also ensure that we are listening for observer class update events
+    def register_observer(observer)
+      @observer_mutex.synchronize do
+        log "EventListener: registering observer #{observer.class} #{observer.id}"
+        @observers[observer_key_for(observer.class, observer.id)] = observer.observe_events(client)
+      end
     end
 
-    # Delete a queue for an observer. This also purges all messages associated with it
+    # Unregister an observer instance, and cancel consumption of messages. Any pre-fetched messages will be returned to the queue.
     def unregister_observer(observer_class, observer_id)
       @observer_mutex.synchronize do
         log "EventListener: un-registering observer #{observer_class} #{observer_id}"
-        queue_name = observer_class.constantize.event_queue_name(observer_id)
-        client.delete_queue(queue_name)
-        @observers.delete(observer_key_for(observer_class, observer_id))
+        if (consumer = @observers.delete(observer_key_for(observer_class, observer_id)))
+          consumer.cancel
+        end
       end
     end
 
     # Create or return the observer queue which listens for ModelWatcher events
     def observer_queue
-      @observer_queue ||= client.create_queue("#{name}.listener", models_exchange, &method(:handle_observer_event))
-    end
-
-    # Register the observer class watcher
-    def register_observer_class(observer_class)
-      @observer_mutex.synchronize do
-        return if @observed_models.include?(observer_class)
-        @observed_models << observer_class
-        log "EventListener: registering observer class #{observer_class}"
-        observer_queue.bind(models_exchange, routing_key: "#{Isimud.model_watcher_schema}.#{observer_class.base_class.name}.*")
-      end
+      @observer_queue ||= client.create_queue([name, 'listener', Socket.gethostname, Process.pid].join('.'),
+                                              models_exchange,
+                                              queue_options:      {exclusive: true},
+                                              subscribe_options:  {manual_ack: true})
     end
 
     def observer_key_for(type, id)