sanger_warren 0.1.0 → 0.3.0

data/lib/warren/handler.rb

@@ -7,6 +7,22 @@ module Warren
   # A {Warren::Handler} provides an interface for sending messages to either
   # a message queue, a log, or an internal store for testing purposes.
   module Handler
+    #
+    # Generates a template for routing keys for the given prefix, or a template
+    # that returns the provided routing key if no prefix is supplied.
+    #
+    # @example With a prefix
+    #   template = Warren::Handler.routing_key_template('example') # => 'example.%s'
+    #   format(template, 'routing.key') #=> 'example.routing.key'
+    #
+    # @example Without a prefix
+    #   template = Warren::Handler.routing_key_template(nil) # => '%s'
+    #   format(template, 'routing.key') #=> 'routing.key'
+    #
+    # @param prefix [String, nil] The prefix to use in the template
+    #
+    # @return [String] A template for generating routing keys
+    #
     def self.routing_key_template(prefix)
       prefix ? "#{prefix}.%s" : '%s'
     end

data/lib/warren/handler/base.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Warren
+  module Handler
+    # Base class
+    class Base
+      #
+      # Provide API compatibility with the RabbitMQ versions
+      # Do nothing in this case
+      #
+      def connect; end
+
+      #
+      # Provide API compatibility with the RabbitMQ versions
+      # Do nothing in this case
+      #
+      def disconnect; end
+    end
+  end
+end

data/lib/warren/handler/broadcast.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require 'bunny'
+require 'forwardable'
+require 'connection_pool'
+require_relative 'base'
 
 module Warren
   module Handler
@@ -8,36 +11,60 @@ module Warren
     # Class Warren::Broadcast provides a connection pool of
     # threadsafe RabbitMQ channels for broadcasting messages
     #
-    class Broadcast
-      # Wraps a {Bunny::Channel}
+    class Broadcast < Warren::Handler::Base
+      # Wraps a Bunny::Channel
+      # @see https://rubydoc.info/gems/bunny/Bunny/Channel
       class Channel
-        def initialize(bun_channel, routing_key_template:, exchange: nil)
+        extend Forwardable
+
+        attr_reader :routing_key_prefix
+
+        def_delegators :@bun_channel, :close, :exchange, :queue, :prefetch, :ack, :nack
+
+        def initialize(bun_channel, routing_key_prefix:, exchange: nil)
           @bun_channel = bun_channel
           @exchange_name = exchange
-          @routing_key_template = routing_key_template
+          @routing_key_prefix = routing_key_prefix
+          @routing_key_template = Handler.routing_key_template(routing_key_prefix)
         end
 
+        # Publishes `message` to the configured exchange
+        #
+        # @param message [#routing_key,#payload] A message should respond to routing_key and payload.
+        #                                        @see Warren::Message::Full
+        #
+        # @return [Warren::Handler::Broadcast::Channel] returns self for chaining
+        #
         def <<(message)
-          exchange.publish(message.payload, routing_key: key_for(message))
-          self
+          publish(message)
         end
 
-        def close
-          @bun_channel.close
+        # Publishes `message` to `exchange` (Defaults to configured exchange)
+        #
+        # @param message [#routing_key,#payload] A message should respond to routing_key and payload.
+        #                                        @see Warren::Message::Full
+        # @param exchange [Bunny::Exchange] The exchange to publish to
+        #
+        # @return [Warren::Handler::Broadcast::Channel] returns self for chaining
+        #
+        def publish(message, exchange: configured_exchange)
+          exchange.publish(message.payload, routing_key: key_for(message), headers: message.headers)
+          self
         end
 
         private
 
-        def exchange
+        def configured_exchange
           raise StandardError, 'No exchange configured' if @exchange_name.nil?
 
-          @exchange ||= @bun_channel.topic(@exchange_name, auto_delete: false, durable: true)
+          @configured_exchange ||= exchange(@exchange_name, auto_delete: false, durable: true, type: :topic)
         end
 
         def key_for(message)
           @routing_key_template % message.routing_key
         end
       end
+
       #
       # Creates a warren but does not connect.
       #
@@ -47,10 +74,11 @@ module Warren
       # @param [String,nil] routing_key_prefix The prefix to pass before the routing key.
       #                                        Can be used to ensure environments remain distinct.
       def initialize(exchange:, routing_key_prefix:, server: {}, pool_size: 14)
+        super()
         @server = server
         @exchange_name = exchange
         @pool_size = pool_size
-        @routing_key_template = Handler.routing_key_template(routing_key_prefix)
+        @routing_key_prefix = routing_key_prefix
       end
 
       #
@@ -74,12 +102,12 @@ module Warren
       end
 
       #
-      # Yields an exchange which gets returned to the pool on block closure
-      #
+      # Yields an {Warren::Handler::Broadcast::Channel} which gets returned to the pool on block closure
       #
       # @return [void]
       #
-      # @yieldreturn [Warren::Broadcast::Channel] A rabbitMQ channel that sends messages to the configured exchange
+      # @yieldparam [Warren::Handler::Broadcast::Channel] A rabbitMQ channel that sends messages to the configured
+      #                                                    exchange
       def with_channel(&block)
         connection_pool.with(&block)
       end
@@ -90,7 +118,7 @@ module Warren
       #
       # @param [Warren::Message] message The message to broadcast. Must respond to #routing_key and #payload
       #
-      # @return [Warren::Broadcast] Returns itself to allow chaining. But you're
+      # @return [Warren::Handler::Broadcast] Returns itself to allow chaining. But you're
       #                             probably better off using #with_channel
       #                             in that case
       #
@@ -99,16 +127,24 @@ module Warren
         self
       end
 
+      def new_channel(worker_count: 1)
+        Channel.new(session.create_channel(nil, worker_count), exchange: @exchange_name,
+                                                               routing_key_prefix: @routing_key_prefix)
+      end
+
       private
 
+      def server_connection
+        ENV.fetch('WARREN_CONNECTION_URI', @server)
+      end
+
       def session
-        @session ||= Bunny.new(@server)
+        @session ||= Bunny.new(server_connection)
       end
 
       def connection_pool
         @connection_pool ||= start_session && ConnectionPool.new(size: @pool_size, timeout: 5) do
-          Channel.new(session.create_channel, exchange: @exchange_name,
-                                              routing_key_template: @routing_key_template)
+          new_channel
         end
       end
 

data/lib/warren/handler/log.rb

@@ -1,23 +1,45 @@
 # frozen_string_literal: true
 
+require_relative 'base'
+
 module Warren
   module Handler
     # Class Warren::Log provides a dummy RabbitMQ
     # connection pool for use during development
-    class Log
-      # Mimics a {Bunny::Channel} but instead passes out to a logger
+    class Log < Warren::Handler::Base
+      # Mimics a {Broadcast::Channel} but instead passes out to a logger
       class Channel
         def initialize(logger, routing_key_template: '%s')
           @logger = logger
           @routing_key_template = routing_key_template
         end
 
+        # Logs `message` to the configured logger
+        #
+        # @param message [#routing_key,#payload] A message should respond to routing_key and payload.
+        #                                        @see Warren::Message::Full
+        #
+        # @return [Warren::Handler::Broadcast::Channel] returns self for chaining
+        #
         def <<(message)
           @logger.info "Published: #{key_for(message)}"
           @logger.debug "Payload: #{message.payload}"
           self
         end
 
+        def exchange(name, options)
+          @logger.debug "Declared exchange: #{name}, #{options.inspect}"
+          Exchange.new(name, options)
+        end
+
+        def queue(name, options)
+          @logger.debug "Declared queue: #{name}, #{options.inspect}"
+          Queue.new(@logger, name)
+        end
+
+        # NOOP - Provided for API compatibility
+        def prefetch(number); end
+
         private
 
         def key_for(message)
@@ -25,20 +47,38 @@ module Warren
         end
       end
 
+      # Small object to track exchange properties for logging purposes
+      Exchange = Struct.new(:name, :options)
+
+      # Queue class to provide extended logging in development mode
+      class Queue
+        def initialize(logger, name)
+          @logger = logger
+          @name = name
+        end
+
+        def bind(exchange, options)
+          @logger.debug "Bound queue #{@name}: #{exchange}, #{options.inspect}"
+        end
+
+        def subscribe(options)
+          @logger.debug "Subscribed to queue #{@name}: #{options.inspect}"
+          @logger.warn 'This is a Warren::Handler::Log no messages will be processed'
+          nil
+        end
+      end
+
       attr_reader :logger
 
       def initialize(logger:, routing_key_prefix: nil)
+        super()
         @logger = logger
         @routing_key_template = Handler.routing_key_template(routing_key_prefix)
       end
 
-      #
-      # Provide API compatibility with the RabbitMQ versions
-      # Do nothing in this case
-      #
-      def connect; end
-
-      def disconnect; end
+      def new_channel
+        Channel.new(@logger, routing_key_template: @routing_key_template)
+      end
 
       #
       # Yields a Warren::Log::Channel
@@ -48,7 +88,7 @@ module Warren
       #
       # @yieldreturn [Warren::Log::Channel] A rabbitMQ channel that logs messaged to the test warren
       def with_channel
-        yield Channel.new(@logger, routing_key_template: @routing_key_template)
+        yield new_channel
       end
 
       #

data/lib/warren/handler/test.rb

@@ -1,10 +1,57 @@
 # frozen_string_literal: true
 
+require_relative 'base'
+
 module Warren
   module Handler
     # Class Warren::Test provides provides a dummy RabbitMQ
-    # connection pool for use during testing
-    class Test
+    # connection pool for use during testing.
+    #
+    # = Set up a test warren
+    #
+    # By default, the test warren is disabled during testing to avoid storing
+    # messages unnecessarily. Instead you must explicitly enable it when you
+    # wish to test message receipt.
+    #
+    # If using rspec it is suggested that you add the following to your
+    # spec_helper.rb
+    #
+    #   config.around(:each, warren: true) do |ex|
+    #     Warren.handler.enable!
+    #     ex.run
+    #     Warren.handler.disable!
+    #   end
+    #
+    # = Making assertions
+    #
+    # It is possible to query the test warren about the messages it has seen.
+    # In particular the following methods are useful:
+    #
+    # {render:#messages}
+    #
+    # {render:#last_message}
+    #
+    # {render:#message_count}
+    #
+    # {render:#messages_matching}
+    #
+    # = Example
+    #
+    #   describe QcResult, warren: true do
+    #     let(:warren) { Warren.handler }
+    #
+    #     setup { warren.clear_messages }
+    #     let(:resource) { build :qc_result }
+    #     let(:routing_key) { 'test.message.qc_result.' }
+    #
+    #     it 'broadcasts the resource' do
+    #       resource.save!
+    #       expect(warren.messages_matching(routing_key)).to eq(1)
+    #     end
+    #   end
+    class Test < Warren::Handler::Base
+      # Warning displayed if the user attempts to make assertions against the
+      # handler without having enabled it.
       DISABLED_WARNING = <<~DISABLED_WARREN
         Test made against a disabled warren.
         Warren::Handler::Test must be explicitly enabled to track messages,
@@ -23,17 +70,25 @@ module Warren
 
         You can then tag tests with warren: true to enable warren testing.
       DISABLED_WARREN
-      # Stand in for {Bunny::Channel}, provides a store of messages to use
+      # Stand in for {Broadcast::Channel}, provides a store of messages to use
       # in test assertions
       class Channel
         def initialize(warren)
           @warren = warren
         end
 
+        # Records `message` for testing purposes
+        #
+        # @param message [#routing_key,#payload] A message should respond to routing_key and payload.
+        #                                        @see Warren::Message::Full
+        #
+        # @return [Warren::Handler::Broadcast::Channel] returns self for chaining
+        #
         def <<(message)
           @warren << message
         end
       end
+
       #
       # Creates a test warren with no messages.
       # Test warrens are shared across all threads.
@@ -41,45 +96,74 @@ module Warren
       # @param [_] _args Configuration arguments are ignored.
       #
       def initialize(*_args)
+        super()
         @messages = []
+        @exchanges = []
         @enabled = false
       end
 
       #
-      # Provide API compatibility with the RabbitMQ versions
-      # Do nothing in this case
-      #
-      def connect; end
-
-      def disconnect; end
-
-      #
-      # Yields an exchange which gets returned to the pool on block closure
-      #
+      # Yields a new channel, which proxies all message back to {messages} on the
+      # {Warren::Handler::Test}
       #
       # @return [void]
       #
       # @yieldreturn [Warren::Test::Channel] A rabbitMQ channel that logs messaged to the test warren
       def with_channel
-        yield Channel.new(self)
+        yield new_channel
       end
 
+      #
+      # Returns a new channel, which proxies all message back to {messages} on the
+      # {Warren::Handler::Test}
+      #
+      # @return [Warren::Test::Channel] A rabbitMQ channel that logs messaged to the test warren
+      #
+      def new_channel
+        Channel.new(@logger, routing_key_template: @routing_key_template)
+      end
+
+      #
+      # Clear any logged messaged
+      #
+      # @return [Array] The new empty array, lacking messages
+      #
       def clear_messages
         @messages = []
+        @exchanges = []
       end
 
+      #
+      # Returns the last message received by the warren
+      #
+      # @return [#routing_key#payload] The last message object received by the warren
+      #
       def last_message
         messages.last
       end
 
+      #
+      # Returns the total number message received by the warren since it was enabled
+      #
+      # @return [Integer] The total number of messages
+      #
       def message_count
         messages.length
       end
 
+      #
+      # Returns the total number message received by the warren matching the given
+      # routing_key since it was enabled
+      #
+      # @param routing_key [String] The routing key to filter by
+      #
+      # @return [Integer] The number of matching messages
+      #
       def messages_matching(routing_key)
         messages.count { |message| message.routing_key == routing_key }
       end
 
+      # Enable the warren
       def enable!
         @enabled = true
         clear_messages
@@ -91,6 +175,9 @@ module Warren
         clear_messages
       end
 
+      # Returns an array of all message received by the warren since it was enabled
+      #
+      # @return [Array<#routing_key#payload>] All received messages
       def messages
         raise_if_not_tracking
         @messages