sanger_warren 0.1.0 → 0.2.0.rc1

data/lib/warren/exceptions.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Warren
+  # Exceptions used by the warren gem
+  module Exceptions
+    # raise {Warren::Exceptions::TemporaryIssue} in a {Warren::Subscriber} to
+    # nack the message, requeuing it, and sending the consumers into sleep
+    # mode until the issue resolves itself.
+    TemporaryIssue = Class.new(StandardError)
+
+    # {Warren::Exceptions::Exceptions::MultipleAcknowledgements} is raised if a message
+    # is acknowledged, or rejected (nacked) multiple times.
+    MultipleAcknowledgements = Class.new(StandardError)
+  end
+end

data/lib/warren/fox.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'bunny'
+require 'warren'
+require 'warren/helpers/state_machine'
+require 'warren/subscriber/base'
+require 'warren/log_tagger'
+require 'warren/framework_adaptor/rails_adaptor'
+
+module Warren
+  # A fox is a rabbitMQ consumer. It handles subscription to the queue
+  # and passing message on to the registered Subscriber
+  class Fox
+    # A little cute fox emoji to easily flag output from the consumers
+    FOX = '🦊'
+
+    extend Forwardable
+    extend Warren::Helpers::StateMachine
+    # Maximum wait time between database retries: 5 minutes
+    MAX_RECONNECT_DELAY = 60 * 5
+
+    attr_reader :state, :subscription, :consumer_tag
+
+    #
+    # Creates a fox, a RabbitMQ consumer.
+    # Subscribes to the queues defined in `subscription`
+    # and passes messages on to the subscriber
+    #
+    # @param name [String] The name of the consumer
+    # @param subscription [Warren::Subscription] Describes the queue to subscribe to
+    # @param adaptor [#recovered?,#handle,#env] An adaptor to handle framework specifics
+    #
+    def initialize(name:, subscription:, adaptor:, subscribed_class:)
+      @consumer_tag = "#{adaptor.env}_#{name}_#{Process.pid}"
+      @subscription = subscription
+      @logger = Warren::LogTagger.new(logger: adaptor.logger, tag: "#{FOX} #{@consumer_tag}")
+      @adaptor = adaptor
+      @subscribed_class = subscribed_class
+      @state = :initialized
+    end
+
+    states :stopping, :stopped, :paused, :starting, :started, :running
+    def_delegators :@logger, :warn, :info, :error, :debug
+
+    #
+    # Starts up the fox, automatically registering the configured queues and bindings
+    # before subscribing to the queue.
+    #
+    # @return [Void]
+    #
+    def run!
+      starting!
+      subscription.activate! # Set up the queues
+      running!            # Transition to running state
+      subscribe!          # Subscribe to the queue
+
+      info { 'Started consumer' }
+    end
+
+    #
+    # Stop the consumer and unsubscribes from the queue. Blocks until fully unsubscribed.
+    #
+    # @return [Void]
+    #
+    def stop!
+      info { 'Stopping consumer' }
+      stopping!
+      unsubscribe!
+      info { 'Stopped consumer' }
+      stopped!
+    end
+
+    #
+    # Temporarily unsubscribes the consumer, and schedules an attempted recovery.
+    # Recovery is triggered by the {#attempt_recovery} method which gets called
+    # periodically by {Warren::Client}
+    #
+    # @return [Void]
+    #
+    def pause!
+      return unless running?
+
+      unsubscribe!
+      @recovery_attempts = 0
+      @recover_at = Time.now
+      paused!
+    end
+
+    # If the fox is paused, and a recovery attempt is scheduled, will prompt
+    # the framework adaptor to attempt to recover. (Such as reconnecting to the
+    # database). If this operation is successful will resubscribe to the queue,
+    # otherwise a further recovery attempt will be scheduled. Successive recovery
+    # attempts will be gradually further apart, up to the MAX_RECONNECT_DELAY
+    # of 5 minutes.
+    def attempt_recovery
+      return unless paused? && recovery_due?
+
+      warn { "Attempting recovery: #{@recovery_attempts}" }
+      if recovered?
+        running!
+        subscribe!
+      else
+        @recovery_attempts += 1
+        @recover_at = Time.now + delay_for_attempt
+      end
+    end
+
+    private
+
+    # Our consumer operates in another thread. It is non blocking.
+    def subscribe!
+      raise StandardError, 'Consumer already exists' unless @consumer.nil?
+
+      @consumer = @subscription.subscribe(@consumer_tag) do |delivery_info, properties, payload|
+        process(delivery_info, properties, payload)
+      end
+    end
+
+    # Cancels the consumer and unregisters it
+    def unsubscribe!
+      info { 'Unsubscribing' }
+      @consumer&.cancel
+      @consumer = nil
+      info { 'Unsubscribed' }
+    end
+
+    def delay_for_attempt
+      [2**@recovery_attempts, MAX_RECONNECT_DELAY].min
+    end
+
+    def recovery_due?
+      Time.now > @recover_at
+    end
+
+    def recovered?
+      @adaptor.recovered?
+    end
+
+    def process(delivery_info, properties, payload)
+      log_message(payload) do
+        message = @subscribed_class.new(self, delivery_info, properties, payload)
+        @adaptor.handle { message._process_ }
+      rescue Warren::Exceptions::TemporaryIssue => e
+        warn { "Temporary Issue: #{e.message}" }
+        pause!
+        message.requeue(e)
+      rescue StandardError => e
+        message.dead_letter(e)
+      end
+    end
+
+    def log_message(payload)
+      debug { 'Started message process' }
+      debug { payload }
+      yield
+    ensure
+      debug { 'Finished message process' }
+    end
+  end
+end

data/lib/warren/framework_adaptor/rails_adaptor.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Warren
+  module FrameworkAdaptor
+    # The RailsAdaptor provides error handling and application
+    # loading for Rails applications
+    class RailsAdaptor
+      # Matches errors associated with database connection loss.
+      # To understand exactly how this works, we need to go under the hood of
+      # `rescue`.
+      # When an exception is raised in Ruby, the interpreter begins unwinding
+      # the stack, looking for `rescue` statements. For each one it
+      # finds it performs the check `ExceptionClass === raised_exception`,
+      # and if this returns true, it enters the rescue block, otherwise it
+      # continues unwinding the stack.
+      # Under normal circumstances Class#=== returns true for instances of that
+      # class. Here we override that behaviour and explicitly check for a
+      # database connection instead. This ensures that regardless of what
+      # exception gets thrown if we loose access to the database, we correctly
+      # handle the message
+      class ConnectionMissing
+        def self.===(_)
+          # We used to inspect the exception, and try and check it against a list
+          # of errors that might indicate connectivity issues. But this list
+          # just grew and grew over time. So instead we just explicitly check
+          # the outcome
+          !ActiveRecord::Base.connection.active?
+        rescue StandardError => _e
+          # Unfortunately ActiveRecord::Base.connection.active? can throw an
+          # exception if it is unable to connect, and furthermore the class
+          # depends on the adapter used.
+          true
+        end
+      end
+
+      def recovered?
+        ActiveRecord::Base.connection.reconnect!
+        true
+      rescue StandardError
+        false
+      end
+
+      def handle
+        with_connection do
+          yield
+        rescue ConnectionMissing => e
+          raise Warren::Exceptions::TemporaryIssue, e.message
+        end
+      end
+
+      def with_connection
+        begin
+          ActiveRecord::Base.connection
+        rescue StandardError => e
+          raise Warren::Exceptions::TemporaryIssue, e.message
+        end
+
+        yield
+      ensure
+        ActiveRecord::Base.clear_active_connections!
+      end
+
+      def env
+        Rails.env
+      end
+
+      def logger
+        Rails.logger
+      end
+
+      def load_application
+        $stdout.puts 'Loading application...'
+        require './config/environment'
+        Warren.load_configuration
+        $stdout.puts 'Loaded!'
+      rescue LoadError
+        # Need to work out an elegant way to handle non-rails
+        # apps
+        $stdout.puts 'Could not auto-load application'
+      end
+    end
+  end
+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,9 +11,14 @@ 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
+        extend Forwardable
+
+        def_delegators :@bun_channel, :close, :exchange, :queue, :prefetch, :ack, :nack
+
         def initialize(bun_channel, routing_key_template:, exchange: nil)
           @bun_channel = bun_channel
           @exchange_name = exchange
@@ -18,26 +26,23 @@ module Warren
         end
 
         def <<(message)
-          exchange.publish(message.payload, routing_key: key_for(message))
+          default_exchange.publish(message.payload, routing_key: key_for(message))
           self
         end
 
-        def close
-          @bun_channel.close
-        end
-
         private
 
-        def exchange
+        def default_exchange
           raise StandardError, 'No exchange configured' if @exchange_name.nil?
 
-          @exchange ||= @bun_channel.topic(@exchange_name, auto_delete: false, durable: true)
+          @default_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,6 +52,7 @@ 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
@@ -74,12 +80,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 +96,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 +105,24 @@ module Warren
         self
       end
 
+      def new_channel
+        Channel.new(session.create_channel(nil, 1), exchange: @exchange_name,
+                                                    routing_key_template: @routing_key_template)
+      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,11 +1,13 @@
 # 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
@@ -18,6 +20,19 @@ module Warren
           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 +40,37 @@ module Warren
         end
       end
 
+      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 +80,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
 
       #