proletariat 0.0.1

data/lib/proletariat/subscriber.rb

@@ -0,0 +1,249 @@
+module Proletariat
+  # Internal: Creates, binds and listens on a RabbitMQ queue. Forwards
+  #           messages to a given listener.
+  class Subscriber
+    include Concurrent::Runnable
+
+    include Concerns::Logging
+
+    # Public: Creates a new Subscriber instance.
+    #
+    # connection    - An open Bunny::Session object.
+    # exchange_name - A String of the RabbitMQ topic exchange.
+    # queue_config  - A QueueConfig value object.
+    def initialize(connection, listener, queue_config)
+      @connection   = connection
+      @listener     = listener
+      @queue_config = queue_config
+
+      @channel      = @connection.create_channel
+
+      @channel.prefetch queue_config.prefetch
+
+      @exchange     = @channel.topic queue_config.exchange_name, durable: true
+      @bunny_queue  = @channel.queue queue_config.queue_name,
+                                     durable: true,
+                                     auto_delete: queue_config.auto_delete
+
+      bind_queue
+    end
+
+    # Internal: Called by the Concurrent framework on run. Used here to start
+    #           consumption of the queue and to log the status of the
+    #           subscriber.
+    #
+    # Returns nil.
+    def on_run
+      start_consumer
+      log_info 'Now online'
+
+      nil
+    end
+
+    # Internal: Called by the Concurrent framework on run. Used here to stop
+    #           consumption of the queue and to log the status of the
+    #           subscriber.
+    #
+    # Returns nil.
+    def on_stop
+      log_info 'Attempting graceful shutdown.'
+      stop_consumer
+      log_info 'Now offline'
+    end
+
+    # Internal: Called by the Concurrent framework to perform work. Used here
+    #           acknowledge RabbitMQ messages.
+    #
+    # Returns nil.
+    def on_task
+      ready_acknowledgers.each do |acknowledger|
+        acknowledger.acknowledge_on_channel channel
+        acknowledgers.delete acknowledger
+      end
+    end
+
+    # Public: Purge the RabbitMQ queue.
+    #
+    # Returns nil.
+    def purge
+      bunny_queue.purge
+
+      nil
+    end
+
+    private
+
+    # Internal: Returns the Bunny::Queue in use.
+    attr_reader :bunny_queue
+
+    # Internal: Returns the Bunny::Channel in use.
+    attr_reader :channel
+
+    # Internal: Returns the Bunny::Exchange in use.
+    attr_reader :exchange
+
+    # Internal: Returns the listener object.
+    attr_reader :listener
+
+    # Internal: Returns the queue_config in use.
+    attr_reader :queue_config
+
+    def acknowledgers
+      @acknowledgers ||= []
+    end
+
+    # Internal: Binds bunny_queue to the exchange via each routing key
+    #           specified in the queue_config.
+    #
+    # Returns nil.
+    def bind_queue
+      queue_config.routing_keys.each do |key|
+        bunny_queue.bind exchange, routing_key: key
+      end
+
+      nil
+    end
+
+    # Internal: Get acknowledgers for messages whose work has completed.
+    #
+    # Returns an Array of Acknowledgers.
+    def ready_acknowledgers
+      acknowledgers.select do |acknowledger|
+        acknowledger.ready_to_acknowledge?
+      end
+    end
+
+    # Internal: Starts a consumer on the queue. The consumer forwards all
+    #           message bodies to listener#post.
+    #
+    # Returns nil.
+    def start_consumer
+      @consumer = bunny_queue.subscribe ack: true do |info, properties, body|
+        future = listener.post?(body)
+        acknowledgers << Acknowledger.new(future, info.delivery_tag)
+
+        nil
+      end
+
+      nil
+    end
+
+    # Internal: Stops any active consumer. Waits for acknowledgement queue to
+    #           drain before returning.
+    #
+    # Returns nil.
+    def stop_consumer
+      @consumer.cancel if @consumer
+      wait_for_acknowledgers if acknowledgers.any?
+
+      nil
+    end
+
+    # Internal: Makes blocking calls for each unacknowledged message until all
+    #           messages are acknowledged.
+    #
+    # Returns nil.
+    def wait_for_acknowledgers
+      log_info 'Waiting for unacknowledged messages.'
+      while acknowledgers.any?
+        acknowledger = acknowledgers.pop
+        acknowledger.block_until_acknowledged channel
+      end
+
+      nil
+    end
+
+    # Internal: Used to watch the state of dispatched Work and send ack/nack
+    #           to a RabbitMQ channel.
+    class Acknowledger
+      # Public: Maximum time in seconds to wait synchronously for an
+      #         acknowledgement.
+      MAX_BLOCK_TIME = 5
+
+      # Public: Creates a new Acknowledger instance.
+      #
+      # future       - A future-like object holding the Worker response.
+      # delivery_tag - The RabbitMQ delivery tag to be used when ack/nacking.
+      def initialize(future, delivery_tag)
+        @future       = future
+        @delivery_tag = delivery_tag
+      end
+
+      # Public: Retrieves the value from the future and sends the relevant
+      #         acknowledgement on a given channel. Logs a warning if the
+      #         future value is unexpected.
+      #
+      # channel - The Bunny::Channel to receive the acknowledgement.
+      #
+      # Returns nil.
+      def acknowledge_on_channel(channel)
+        if future.fulfilled?
+          acknowledge_success(channel)
+        elsif future.rejected?
+          acknowledge_error(channel)
+        end
+
+        nil
+      end
+
+      # Public: Blocks until acknowledgement completes.
+      #
+      # channel - The Bunny::Channel to receive the acknowledgement.
+      #
+      # Returns nil.
+      def block_until_acknowledged(channel)
+        future.value(MAX_BLOCK_TIME)
+        acknowledge_on_channel(channel)
+
+        nil
+      end
+
+      # Public: Gets the readiness of the future for acknowledgement use.
+      #
+      # Returns true if future is fulfilled or rejected.
+      def ready_to_acknowledge?
+        future.state != :pending
+      end
+
+      private
+
+      # Internal: Dispatches acknowledgements for non-errored worker responses.
+      #           Maps symbol value to acknowledgement strategies.
+      #
+      # channel - The Bunny::Channel to receive the acknowledgement.
+      #
+      # Returns nil.
+      def acknowledge_success(channel)
+        case future.value
+        when :ok then channel.acknowledge delivery_tag
+        when :drop then channel.reject delivery_tag, false
+        when :requeue then channel.reject delivery_tag, true
+        else
+          Proletariat.logger.warn 'Unexpected return value from #work.'
+          channel.reject delivery_tag, false
+        end
+
+        nil
+      end
+
+      # Internal: Dispatches acknowledgements for errored worker responses.
+      #           Requeues messages and logs the error.
+      #
+      # channel - The Bunny::Channel to receive the acknowledgement.
+      #
+      # Returns nil.
+      def acknowledge_error(channel)
+        Proletariat.logger.error future.reason
+        channel.reject delivery_tag, true
+
+        nil
+      end
+
+      # Internal: Returns the RabbitMQ delivery tag.
+      attr_reader :delivery_tag
+
+      # Internal: Returns the future-like object holding the Worker response.
+      attr_reader :future
+    end
+  end
+end

data/lib/proletariat/testing/expectation.rb

@@ -0,0 +1,15 @@
+module Proletariat
+  module Testing
+    # Internal: Defines a quantity of messages you expect to receive on a set
+    #         of topics.
+    class Expectation < Struct.new(:topics, :quantity)
+      # Public: Builds a new duplicate of current instance with different
+      #         topics.
+      #
+      # Returns a new instance of Expectation.
+      def on_topic(*topics)
+        Expectation.new(topics, quantity)
+      end
+    end
+  end
+end

data/lib/proletariat/testing/expectation_guarantor.rb

@@ -0,0 +1,145 @@
+module Proletariat
+  module Testing
+    # Internal: Executes a block and ensures given expectations are satisfied
+    #           before continuing.
+    class ExpectationGuarantor
+      # Public: An error which will be raised if the expectation is not
+      #         satisfied within the timeout.
+      class MessageTimeoutError < RuntimeError; end
+
+      # Public: Default time to wait for expectation to be satisfied.
+      MESSAGE_TIMEOUT = 10
+
+      # Public: Interval at which to check expectation is satisfied.
+      MESSAGE_CHECK_INTERVAL = 0.2
+
+      # Public: Creates a new ExpectationGuarantor instance.
+      #
+      # expectations - An Array of Expectations to be checked.
+      # block        - The block of code within which the expectations should
+      #                be satisfied.
+      def initialize(expectations, &block)
+        @connection  = Proletariat.runner.connection
+        @counters    = []
+        @subscribers = []
+
+        expectations.each do |expectation|
+          queue_config = generate_queue_config_for_topic(expectation.topics)
+          counter = MessageCounter.new(expectation.quantity)
+          counters << counter
+          subscribers << Subscriber.new(connection, counter, queue_config)
+        end
+
+        @block = block
+      end
+
+      # Public: Execute the blocks and waits for the expectations to be met.
+      #
+      # Returns nil if expectations are met within timeout.
+      # Raises MessageTimeoutError if expectations are not met within timeout.
+      def guarantee
+        run_subscribers
+
+        block.call
+
+        timer = 0.0
+
+        until passed?
+          fail MessageTimeoutError if timer > MESSAGE_TIMEOUT
+          sleep MESSAGE_CHECK_INTERVAL
+          timer += MESSAGE_CHECK_INTERVAL
+        end
+
+        stop_subscribers
+
+        nil
+      end
+
+      private
+
+      # Internal: Returns the block of code in which the expectations should be
+      #           satisfied.
+      attr_reader :block
+
+      # Internal: Returns an open Bunny::Session object.
+      attr_reader :connection
+
+      # Internal: Returns an array of MessageCounter instances.
+      attr_reader :counters
+
+      # Internal: Returns an array of Subscriber instances.
+      attr_reader :subscribers
+
+      def generate_queue_config_for_topic(topics)
+        QueueConfig.new('', Proletariat.runner.exchange_name, topics, 1, true)
+      end
+
+      # Internal: Checks each counter to ensure expected messages have arrived.
+      #
+      # Returns true if all counters are satisfied.
+      # Returns false if one or more counters are not satisfied.
+      def passed?
+        counters
+          .map(&:expected_messages_received?)
+          .reduce { |a, e| a && e }
+      end
+
+      # Internal: Starts each subscriber.
+      #
+      # Returns nil.
+      def run_subscribers
+        subscribers.each { |subscriber| subscriber.run! }
+
+        nil
+      end
+
+      # Internal: Stops each subscriber.
+      #
+      # Returns nil.
+      def stop_subscribers
+        subscribers.each { |subscriber| subscriber.stop }
+
+        nil
+      end
+
+      # Internal: Counts incoming messages to test expection satisfaction.
+      class MessageCounter
+        # Public: Creates a new MessageCounter instance.
+        #
+        # expected - The number of messages expected.
+        def initialize(expected)
+          @count    = 0
+          @expected = expected
+        end
+
+        # Public: Checks whether message count satifies expected count.
+        #
+        # Returns true if count is greater or equal to expected.
+        # Returns false if count less than expected.
+        def expected_messages_received?
+          count >= expected
+        end
+
+        # Public: Handles message calls from a subscriber and increments the
+        #         count. Return value matches interface expected by Subscriber.
+        #
+        # message - The contents of the message.
+        #
+        # Returns a future-like object holding an :ok Symbol.
+        def post?(message)
+          self.count = count + 1
+
+          Concurrent::Future.new { :ok }
+        end
+
+        private
+
+        # Internal: Returns the current message count.
+        attr_accessor :count
+
+        # Internal: Returns the expected message count.
+        attr_reader :expected
+      end
+    end
+  end
+end

data/lib/proletariat/testing/fixnum_extension.rb

@@ -0,0 +1,10 @@
+# Public: Extends Fixnum to provide sugar for creating Expectation instances.
+class Fixnum
+  # Public: Builds an Expectation instance which listens for a quantity of
+  #         messages equal to self on any topic.
+  #
+  # Returns a new Expectation instance.
+  def messages
+    Proletariat::Testing::Expectation.new(['#'], self)
+  end
+end

data/lib/proletariat/testing.rb

@@ -0,0 +1,41 @@
+require 'proletariat/testing/expectation'
+require 'proletariat/testing/expectation_guarantor'
+require 'proletariat/testing/fixnum_extension'
+
+module Proletariat
+  # Public: Mixin to aid solve test synchronization issues while still running
+  #         Proletariat the same way you would in production,
+  module Testing
+    # Public: Builds an Expectation instance which listens for a single message
+    #         on any topic.
+    #
+    # Returns a new Expectation instance.
+    def message
+      Proletariat::Testing::Expectation.new(['#'], 1)
+    end
+
+    # Public: Creates and runs a new ExpectationGuarantor from a given list of
+    #         Expectation instances and a block.
+    #
+    # expectations - One or more Expectation instances.
+    # block        - A block within which the expectations should be
+    #                satisfied.
+    #
+    # Examples
+    #
+    #   wait_for 3.messages.on_topic 'email_sent'
+    #   # ... [Time passes]
+    #   # => 'nil'
+    #
+    #   wait_for message.on_topic 'hell_freezes_over'
+    #   # ... [Time passes]
+    #   # => MessageTimeoutError
+    #
+    # Returns nil.
+    def wait_for(*expectations, &block)
+      ExpectationGuarantor.new(expectations, &block).guarantee
+
+      nil
+    end
+  end
+end

data/lib/proletariat/version.rb

@@ -0,0 +1,4 @@
+# Public: Adds a constant for the current version number.
+module Proletariat
+  VERSION = '0.0.1'
+end

data/lib/proletariat/worker.rb

@@ -0,0 +1,131 @@
+module Proletariat
+  # Public: Handles messages from a RabbitMQ queue. Subclasses should
+  #         overwrite the #work method.
+  class Worker < Concurrent::Actor
+    include Concerns::Logging
+
+    # Internal: Called by the Concurrent framework to handle new mailbox
+    #           messages. Overridden in this subclass to call the #work method
+    #           with the given message.
+    #
+    # message - The incoming message.
+    #
+    # Returns nil.
+    def act(message)
+      work message
+    end
+
+    # Internal: Called by the Concurrent framework on actor start. Overridden
+    #           in this subclass to log the status of the worker.
+    #
+    # Returns nil.
+    def on_run
+      super
+
+      log_info 'Now online'
+
+      nil
+    end
+
+    # Internal: Called by the Concurrent framework on actor start. Overridden
+    #         in this subclass to log the status of the worker.
+    #
+    # Returns nil.
+    def on_stop
+      log_info 'Attempting graceful shutdown.'
+      wait_for_work_queue unless queue.empty?
+
+      super
+
+      log_info 'Now offline'
+
+      nil
+    end
+
+    # Public: Handles RabbitMQ messages.
+    #
+    # message - The incoming message.
+    #
+    # Raises NotImplementedError unless implemented in subclass.
+    def work(message)
+      fail NotImplementedError
+    end
+
+    protected
+
+    # Public: Helper method to ease accessing the logger from within #work.
+    #         Sends #info to logger if message provided.
+    #
+    # Examples
+    #
+    #   log 'Background Workers Unite!'
+    #   # Message is logged at info level.
+    #
+    #   log.error 'Something bad happened!'
+    #   # Message is logged at error level.
+    #
+    # Returns the process-wide logger if message not supplied.
+    # Returns nil if message supplied.
+    def log(message = nil)
+      if message
+        Proletariat.logger.info(message)
+
+        nil
+      else
+        Proletariat.logger
+      end
+    end
+
+    # Public: Helper method to ease sending messages from within #work.
+    #
+    # to      - The routing key for the message to as a String. In accordance
+    #           with the RabbitMQ convention you can use the '*' character to
+    #           replace one word and the '#' to replace many words.
+    # message - The message as a String.
+    #
+    # Returns nil.
+    def publish(to, message = '')
+      Proletariat.publish to, message
+
+      nil
+    end
+
+    private
+
+    # Internal: Blocks until each message has been handled by #work.
+    #
+    # Returns nil.
+    def wait_for_work_queue
+      log_info 'Waiting for work queue to drain.'
+
+      work(*queue.pop.message) until queue.empty?
+
+      nil
+    end
+
+    # Internal: Class methods on Worker to provide configuration DSL.
+    module ConfigurationMethods
+      # Public: A configuration method for adding a routing key to be used when
+      #         binding this worker type's queue to an exchange.
+      #
+      # routing_key - A routing key for queue-binding as a String.
+      #
+      # Returns nil.
+      def listen_on(routing_key)
+        routing_keys << routing_key
+
+        nil
+      end
+
+      # Internal: Returns the list of all desired routing keys for this worker
+      #           type
+      #
+      # Returns an Array of routing keys as Strings.
+      def routing_keys
+        @routing_keys ||= []
+      end
+    end
+
+    extend ConfigurationMethods
+  end
+end

data/lib/proletariat.rb

@@ -0,0 +1,87 @@
+require 'proletariat/version'
+
+require 'concurrent'
+require 'bunny'
+require 'logger'
+require 'forwardable'
+
+require 'proletariat/concerns/logging'
+
+require 'proletariat/manager'
+require 'proletariat/publisher'
+require 'proletariat/queue_config'
+require 'proletariat/runner'
+require 'proletariat/subscriber'
+require 'proletariat/worker'
+
+# Public: Creates the Proletariat namespace and holds a process-wide Runner
+#         instance as well as a logger.
+module Proletariat
+  # Public: The default name used for the RabbitMQ topic exchange.
+  DEFAULT_EXCHANGE_NAME = 'proletariat'
+
+  class << self
+    extend Forwardable
+
+    # Public: Delegate lifecycle calls to the process-wide Runner.
+    def_delegators :runner, :run, :run!, :stop, :running?, :publish, :purge
+
+    # Public: Allows the setting of an alternate logger.
+    #
+    # logger - An object which fulfills the role of a Logger.
+    attr_writer :logger
+
+    # Public: Sets the process-wide Runner to an instance initialized with a
+    #         given hash of options.
+    #
+    # options - A Hash of options (default: {}):
+    #             :connection        - An open RabbitMQ::Session object.
+    #             :exchange_name     - The RabbitMQ topic exchange name as a
+    #                                  String.
+    #             :logger            - An object which fulfills the role of a
+    #                                  Logger.
+    #             :publisher_threads - The size of the publisher thread pool.
+    #             :supervisor        - A Supervisor instance.
+    #             :worker_classes    - An Array of Worker subclasses.
+    #             :worker_threads    - The size of the worker thread pool.
+    def configure(options = {})
+      self.logger = options.fetch(:logger, default_logger)
+
+      @runner = Runner.new(defaults.merge(options))
+    end
+
+    # Internal: The logger used if no other is specified via .configure.
+    #
+    # Returns a Logger which logs to STDOUT.
+    def default_logger
+      Logger.new(STDOUT)
+    end
+
+    # Internal: Default process-wide Runner options.
+    #
+    # Returns a Hash of options.
+    def defaults
+      {
+        worker_classes: workers_from_env || []
+      }
+    end
+
+    def logger
+      @logger ||= default_logger
+    end
+
+    def runner
+      @runner ||= Runner.new(defaults)
+    end
+
+    def workers_from_env
+      if ENV['WORKERS']
+        ENV['WORKERS'].split(',').map(&:strip).map do |string|
+          string
+            .split('::')
+            .reduce(Object) { |a, e| a.const_get(e) }
+        end
+      end
+    end
+  end
+end