sanger_warren 0.1.0 → 0.2.0.rc1

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,7 +70,7 @@ 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)
@@ -33,7 +80,12 @@ module Warren
         def <<(message)
           @warren << message
         end
+
+        def add_exchange(name, options)
+          @warren.add_exchange(name, options)
+        end
       end
+
       #
       # Creates a test warren with no messages.
       # Test warrens are shared across all threads.
@@ -41,45 +93,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 chanel, 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 chanel, 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 +172,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
@@ -101,6 +185,10 @@ module Warren
         @messages << message if @enabled
       end
 
+      def add_exchange(name, options)
+        @exchanges << [name, options] if @enabled
+      end
+
       private
 
       def raise_if_not_tracking

data/lib/warren/helpers/state_machine.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Warren
+  # Namespace for utility modules
+  module Helpers
+    # Provides an incredibly simple state machine. It merely lets you define
+    # states with {#state} which defines two methods `{state}!` to transition
+    # into the state and `{state}?` to query if we are in the state.
+    #
+    # == Usage:
+    #
+    # @example Basic usage
+    #   class Machine
+    #     extend Warren::Helpers::StateMachine
+    #     states :started, :started
+    #   end
+    #
+    #   machine = Machine.new
+    #   machine.started!
+    #   machine.started? # => true
+    #   machine.stopped? # => false
+    #   machine.stopped!
+    #   machine.started? # => false
+    #   machine.stopped? # => stopped
+    #
+    module StateMachine
+      #
+      # Define a new state, generates two methods `{state}!` to transition
+      # into the state and `{state}?` to query if we are in the state.
+      #
+      # @param state_name [Symbol, String] The name of the state
+      #
+      # @return [Void]
+      #
+      def state(state_name)
+        define_method(:"#{state_name}!") { @state = state_name }
+        define_method(:"#{state_name}?") { @state == state_name }
+      end
+
+      #
+      # Define new states, generates two methods for each state `{state}!` to
+      # transition into the state and `{state}?` to query if we are in the state.
+      #
+      # @overload push2(state_name, ...)
+      #   @param [Symbol, String] state_name The name of the state
+      #   @param [Symbol, String] ... More states
+      #
+      # @return [Void]
+      #
+      def states(*state_names)
+        state_names.each { |state_name| state(state_name) }
+      end
+    end
+  end
+end

data/lib/warren/log_tagger.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Warren
+  # Applies a tag to any messages sent to the logger.
+  class LogTagger
+    #
+    # Create a new log tagger, which applies a tag to all messages before
+    # forwarding them on to the logger
+    #
+    # @param logger [Logger] A ruby Logger, or compatible interface
+    # @param tag [String] The tag to apply to each message
+    #
+    def initialize(logger:, tag:)
+      @logger = logger
+      @tag = tag
+    end
+
+    #
+    # Define `name` methods which forward on to the similarly named method
+    # on logger, with the tag applied
+    #
+    # @param name [Symbol] The method to define
+    #
+    # @return [Void]
+    def self.level(name)
+      define_method(name) do |arg = nil, &block|
+        if block
+          @logger.public_send(name, arg) { tag(block.call) }
+        else
+          @logger.public_send(name, tag(arg))
+        end
+      end
+    end
+
+    # @!method debug(message)
+    #   Forwards message on to logger with {#tag} prefix
+    #   See Logger::debug
+    level :debug
+    # @!method info(message)
+    #   Forwards message on to logger with {#tag} prefix
+    #   See Logger::info
+    level :info
+    # @!method warn(message)
+    #   Forwards message on to logger with {#tag} prefix
+    #   See Logger::warn
+    level :warn
+    # @!method error(message)
+    #   Forwards message on to logger with {#tag} prefix
+    #   See Logger::error
+    level :error
+
+    private
+
+    def tag(message)
+      "#{@tag}: #{message}"
+    end
+  end
+end

data/lib/warren/message.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-# Namespace to collect message formats
-# A Warren compatible message must implement:
-# routing_key: returns the routing_key for the message
-# payloadL returns the message payload
-
 require_relative 'message/short'
 require_relative 'message/full'
 
+# Namespace to collect message formats
+# A Warren compatible message must implement:
+# routing_key: returns the routing_key for the message
+# payload: returns the message payload
+#
 # Additionally, if you wish to use the Message with the ActiveRecord
 # helpers, then the initialize should take the ActiveRecord::Base object
 # as a single argument

data/lib/warren/message/short.rb

@@ -4,18 +4,55 @@ module Warren
   module Message
     # Light-weight interim message which can be expanded to a full payload later.
     class Short
+      begin
+        include AfterCommitEverywhere
+      rescue NameError
+        # After commit everywhere is not included in the gemfile.
+      end
+
       attr_reader :record
 
-      def initialize(record)
-        @record = record
+      #
+      # Create a 'short' message, where the payload is just the class name and id.
+      # Designed for when you wish to use a delayed broadcast.
+      #
+      # @param record [ActiveRecord::Base] An Active Record object
+      #
+      def initialize(record = nil, class_name: nil, id: nil)
+        if record
+          @class_name = record.class.name
+          @id = record.id
+        else
+          @class_name = class_name
+          @id = id
+        end
+      end
+
+      # Queues the message for broadcast at the end of the transaction. Actually want to make this the default
+      # behaviour, but only realised the need when doing some last minute integration tests. Will revisit this
+      # in the next version. (Or possibly post code review depending)
+      def queue(warren)
+        after_commit { warren << self }
+      rescue NoMethodError
+        raise StandardError, '#queue depends on the after_commit_everywhere gem. Please add this to your gemfile'
       end
 
+      # The routing key for the message.
+      #
+      # @return [String] The routing key
+      #
       def routing_key
-        "queue_broadcast.#{record.class.name.underscore}.#{record.id}"
+        "queue_broadcast.#{@class_name.underscore}.#{@id}"
       end
 
+      #
+      # The contents of the message, a string in the form:
+      # ["<ClassName>",<id>]
+      #
+      # @return [String] The payload of the message
+      #
       def payload
-        [record.class.name, record.id].to_json
+        [@class_name, @id].to_json
       end
     end
   end

data/lib/warren/railtie.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Warren
+  # Railtie for automatic configuration in Rails apps. Reduces the need to
+  # modify the application when adding Warren.
+  # @see https://api.rubyonrails.org/classes/Rails/Railtie.html
+  class Railtie < Rails::Railtie
+    config.to_prepare do
+      Warren.load_configuration
+    end
+  end
+end

data/lib/warren/subscriber/base.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'warren/exceptions'
+
+module Warren
+  # Namespace for warren subscriber objects
+  module Subscriber
+    # A message takes a rabbitMQ message, and handles its acknowledgement
+    # or rejection.
+    class Base
+      extend Forwardable
+
+      # @return [Warren::Fox] The fox consumer that provided the message. Used to acknowledge messages
+      attr_reader :fox
+      # @return [Bunny::DeliveryInfo] Contains the information necessary for acknowledging the message
+      attr_reader :delivery_info
+      # @return [Bunny::MessageProperties] Contains additional information about the received message
+      attr_reader :properties
+      # @return [String] The message contents
+      attr_reader :payload
+
+      # We don't add an active-support dependency, so instead use the plain-ruby
+      # delegators (Supplied by Forwardable)
+      # Essentially syntax is:
+      # def_delegators <target>, *<methods_to_delegate>
+      def_delegators :fox, :subscription, :warn, :info, :error, :debug
+
+      #
+      # Construct a basic subscriber for each received message. Call {#process}
+      # to handle to processing of the message
+      #
+      # @param fox [Warren::Fox] The fox consumer that provided the message. Used to acknowledge messages
+      # @param delivery_info [Bunny::DeliveryInfo] Contains the information necessary for acknowledging the message
+      # @param properties [Bunny::MessageProperties] Contains additional information about the received message
+      # @param payload [String] The message contents
+      #
+      def initialize(fox, delivery_info, properties, payload)
+        @fox = fox
+        @delivery_info = delivery_info
+        @properties = properties
+        @payload = payload
+        @acknowledged = false
+      end
+
+      # Called by {Warren::Fox} to trigger processing of the message and acknowledgment
+      # on success. In most cases the {#process} method should be used to customize behaviour.
+      #
+      # @return [Void]
+      def _process_
+        process
+        ack unless @acknowledged
+      end
+
+      # Triggers processing of the method. Over-ride this in subclasses to customize your
+      # handler.
+      def process
+        true
+      end
+
+      # Reject the message and re-queue ready for
+      # immediate reprocessing.
+      #
+      # @param exception [StandardError] The exception which triggered message requeue
+      #
+      # @return [Void]
+      #
+      def requeue(exception)
+        warn "Re-queue: #{payload}"
+        warn "Re-queue Exception: #{exception.message}"
+        raise_if_acknowledged
+        subscription.nack(delivery_tag, false, true)
+        @acknowledged = true
+        warn 'Re-queue nacked'
+      end
+
+      # Reject the message without re-queuing
+      # Will end up getting dead-lettered
+      #
+      # @param exception [StandardError] The exception which triggered message dead-letter
+      #
+      # @return [Void]
+      #
+      def dead_letter(exception)
+        error "Dead-letter: #{payload}"
+        error "Dead-letter Exception: #{exception.message}"
+        raise_if_acknowledged
+        subscription.nack(delivery_tag)
+        @acknowledged = true
+        error 'Dead-letter nacked'
+      end
+
+      private
+
+      def headers
+        # Annoyingly it appears that a message with no headers
+        # returns nil, not an empty hash
+        properties.headers || {}
+      end
+
+      def delivery_tag
+        delivery_info.delivery_tag
+      end
+
+      # Acknowledge the message as successfully processed.
+      # Will raise {Warren::MultipleAcknowledgements} if the message has been
+      # acknowledged or rejected already.
+      def ack
+        raise_if_acknowledged
+        subscription.ack(delivery_tag)
+        @acknowledged = true
+      end
+
+      def raise_if_acknowledged
+        return unless @acknowledged
+
+        message = "Multiple acks/nacks for: #{payload}"
+        error message
+        raise Warren::Exceptions::MultipleAcknowledgements, message
+      end
+    end
+  end
+end