proletariat 0.0.2 → 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 49905f9a8ecb2a3b12f565f7b6c7e07c7cac6e39
+  data.tar.gz: 76771f1121f542f06a8ee2d9f6f7ffcf07982404
+SHA512:
+  metadata.gz: 5a1e573f1fd1028068f5f91dcd5625d4ddf90052d9711b8c8a85d810db0ea4b0440cb51384040c865eea540cbbf48368dc7b2dacdc770e85fa0430b5f63f887d
+  data.tar.gz: 193ecfabdc6bb3c0d25bda8a8e57a66a77aa6ab830a552f395acc626a88803ef556019556a950201a302089a830d8328fa42690943dca4a9376a345c98200217

data/.rubocop.yml

@@ -0,0 +1,3 @@
+Documentation:
+  Exclude:
+    - spec/*

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 0.0.3
+
+Features:
+
+  - Overhauled configuration (breaking change)
+  - Queues now purged before first cucumber scenario
+
+Code gardening:
+
+  - Decoupling logic from concurrency for better testability
+  - Added tests
+
 ## 0.0.2
 
 Features:

data/README.md

@@ -2,7 +2,7 @@
 
 Lightweight background processing in Ruby powered by RabbitMQ and the excellent concurrent-ruby gem.
 
-[![Code Climate](https://codeclimate.com/repos/52d75c166956805abe000226/badges/bf98213c1d629072560c/gpa.png)](https://codeclimate.com/repos/52d75c166956805abe000226/feed)
+[![Code Climate](https://codeclimate.com/github/SebastianEdwards/proletariat.png)](https://codeclimate.com/github/SebastianEdwards/proletariat)
 
 ### Warning!
 
@@ -100,6 +100,5 @@ Use the provided helpers in your step definitions to synchronize your test suite
 I wanted a library which shared one RabbitMQ connection across all of the workers on a given process. Many hosted RabbitMQ platforms tightly limit the max number of connections.
 
 ## TODO
-- Improve test suite :(
 - Add command line interface
 - Abstract retry strategies

data/lib/proletariat/concurrency/actor.rb

@@ -0,0 +1,71 @@
+module Proletariat
+  # Public: Interface abstraction for Concurrent::Actor. Creates a delegate
+  #         instance from given class and arguments and delegates events to it.
+  class Actor < Concurrent::Actor
+    # Public: Creates a new Actor instance.
+    #
+    # delegate_class - The class to instantiate as a delegate.
+    # *arguments     - The arguments to pass to delegate_class.new
+    def initialize(delegate_class, *arguments)
+      @delegate = delegate_class.new(*arguments)
+    end
+
+    # Internal: Called by the Concurrent framework to handle new mailbox
+    #           messages. Overridden in this subclass to call the #work method
+    #           with the given arguments on the delegate.
+    #
+    # *arguments - The arguments to pass to delegate#work
+    #
+    # Returns nil.
+    def act(*arguments)
+      delegate.work(*arguments)
+    end
+
+    # Internal: Called by the Concurrent framework on actor start. Overridden
+    #           in this subclass to call the #starting and #started methods on
+    #           the delegate.
+    #
+    # Returns nil.
+    def on_run
+      delegate.starting if delegate.respond_to?(:starting)
+
+      super
+
+      delegate.started if delegate.respond_to?(:started)
+
+      nil
+    end
+
+    # Internal: Called by the Concurrent framework on actor start. Overridden
+    #           in this subclass to call the #stopping and #stopped methods on
+    #           the delegate. Ensures queue is drained before calling #stopped.
+    #
+    # Returns nil.
+    def on_stop
+      delegate.stopping if delegate.respond_to?(:stopping)
+
+      wait_for_queue_to_drain unless queue.empty?
+
+      super
+
+      delegate.stopped if delegate.respond_to?(:stopped)
+
+      nil
+    end
+
+    private
+
+    # Internal: Returns the delegate instance.
+    attr_reader :delegate
+
+    # Internal: Blocks until each queued message has been handled by the
+    #           delegate #work method.
+    #
+    # Returns nil.
+    def wait_for_queue_to_drain
+      delegate.work(*queue.pop.message) until queue.empty?
+
+      nil
+    end
+  end
+end

data/lib/proletariat/concurrency/supervisor.rb

@@ -0,0 +1,31 @@
+module Proletariat
+  class Supervisor
+    extend Forwardable
+
+    def_delegators :true_supervisor, :run, :run!, :stop, :running?, :add_worker
+
+    def [](mailbox_name)
+      mailboxes[mailbox_name]
+    end
+
+    def add_supervisor(supervisor, opts = {})
+      true_supervisor.add_worker supervisor, opts.merge(type: :supervisor)
+    end
+
+    def supervise_pool(mailbox_name, threads, actor_class, *arguments)
+      mailboxes[mailbox_name], workers = Actor.pool(threads, actor_class,
+                                                    *arguments)
+      true_supervisor.add_workers workers
+    end
+
+    private
+
+    def mailboxes
+      @mailboxes ||= {}
+    end
+
+    def true_supervisor
+      @true_supervisor ||= Concurrent::Supervisor.new
+    end
+  end
+end

data/lib/proletariat/configuration.rb

@@ -0,0 +1,131 @@
+module Proletariat
+  # Public: Global configuration object. Provides sensible defaults.
+  class Configuration
+    # Public: The default name used for the RabbitMQ topic exchange.
+    DEFAULT_EXCHANGE_NAME = 'proletariat'
+
+    # Public: The default number of threads to use for publishers.
+    DEFAULT_PUBLISHER_THREADS = 2
+
+    # Public: The default number of threads to use for each worker class.
+    DEFAULT_WORKER_THREADS = 3
+
+    # Internal: Sets the RabbitMQ connection.
+    attr_writer :connection
+
+    # Internal: Sets the RabbitMQ topic exchange name.
+    attr_writer :exchange_name
+
+    # Internal: Sets the logger.
+    attr_writer :logger
+
+    # Internal: Sets the number of threads to use for publishers.
+    attr_writer :publisher_threads
+
+    # Internal: Sets the Array of Worker classes to use for background
+    #           processing.
+    attr_writer :worker_classes
+
+    # Internal: Sets the number of threads to use for each Worker class.
+    attr_writer :worker_threads
+
+    # Public: Allows setting of the config attributes via a block.
+    #
+    # block - Block which modifies attributes by accessing them via #config.
+    #
+    # Returns nil.
+    def configure_with_block(&block)
+      ConfigurationDSL.new(self, &block).set_config
+
+      nil
+    end
+
+    # Public: Returns the set connection or defaults to a new, open
+    #         Bunny::Session
+    #
+    # Returns a Bunny::Session.
+    def connection
+      @connection ||= begin
+        new_connection = Bunny.new
+        new_connection.start
+
+        new_connection
+      end
+    end
+
+    # Public: Returns the set name of the exchange or a default.
+    #
+    # Returns a String.
+    def exchange_name
+      @exchange_name ||= DEFAULT_EXCHANGE_NAME
+    end
+
+    # Public: Returns the set logger or a default standard output logger.
+    #
+    # Returns a logger.
+    def logger
+      @logger ||= Logger.new(STDOUT)
+    end
+
+    # Public: Returns the set number of publisher threads or a default.
+    #
+    # Returns a Fixnum.
+    def publisher_threads
+      @publisher_threads ||= DEFAULT_PUBLISHER_THREADS
+    end
+
+    # Public: Returns the set worker classes or a default pulled from the
+    #         WORKERS env variable.
+    #
+    # Returns an array of Worker classes.
+    def worker_classes
+      @worker_classes ||= begin
+        if ENV['WORKERS']
+          WorkerDescriptionParser.parse ENV['WORKERS']
+        else
+          []
+        end
+      end
+    end
+
+    # Public: Returns the set number of worker threads or a default.
+    #
+    # Returns a Fixnum.
+    def worker_threads
+      @worker_threads ||= DEFAULT_WORKER_THREADS
+    end
+
+    private
+
+    # Internal: Handles running a configuration block in a context to allow
+    #           access to the configuration object via a call to #config.
+    class ConfigurationDSL
+      # Public: Creates a new ConfigurationDSL instance.
+      #
+      # configuration - The Configuration instance you intend to update.
+      # block         - The block containing the config settings.
+      def initialize(configuration, &block)
+        @config = configuration
+        @block = block
+      end
+
+      # Public: Runs the configuration block, exposing the configuration
+      #         instance via the #config method.
+      #
+      # Returns nil.
+      def set_config
+        instance_eval(&block)
+
+        nil
+      end
+
+      private
+
+      # Internal: Returns the config block.
+      attr_reader :block
+
+      # Internal: Returns the Configuration instance.
+      attr_reader :config
+    end
+  end
+end

data/lib/proletariat/cucumber.rb

@@ -4,8 +4,12 @@ require 'proletariat/testing'
 World(Proletariat::Testing)
 
 # Hide logs by default.
-AfterConfiguration do |config|
-  Proletariat.logger = Logger.new('/dev/null')
+AfterConfiguration do |_|
+  Proletariat.configure do
+    config.logger = Logger.new('/dev/null')
+  end
+
+  Proletariat.purge
 end
 
 # Ensure Proletariat running before each test.

data/lib/proletariat/manager.rb

@@ -2,27 +2,26 @@ module Proletariat
   # Public: Maintains a pool of worker threads and a RabbitMQ subscriber
   #         thread. Uses information from the worker class to generate queue
   #         config.
-  class Manager < Concurrent::Supervisor
+  class Manager
     # Public: Creates a new Manager instance.
     #
-    # connection    - An open Bunny::Session object.
-    # exchange_name - A String of the RabbitMQ topic exchange.
     # worker_class  - A subclass of Proletariat::Worker to handle messages.
-    # options       - A Hash of additional optional parameters (default: {}):
-    #                 :worker_threads - The size of the worker thread pool.
-    def initialize(connection, exchange_name, worker_class, options = {})
-      super()
+    def initialize(worker_class)
+      @supervisor = Supervisor.new
 
-      @connection     = connection
-      @exchange_name  = exchange_name
-      @worker_class   = worker_class
-      @worker_threads = options.fetch :worker_threads, 3
+      supervisor.supervise_pool('workers', Proletariat.worker_threads,
+                                worker_class)
 
-      create_worker_pool
-      create_subscriber
+      @subscriber = Subscriber.new(supervisor['workers'],
+                                   generate_queue_config(worker_class))
 
-      worker_pool.each { |worker| add_worker worker }
-      add_worker subscriber
+      supervisor.add_worker subscriber
+    end
+
+    # Delegate lifecycle calls to supervisor. Cannot use Forwardable due to
+    # concurrent-ruby API checking implementation.
+    %w(run stop running?).each do |method|
+      define_method(method) { supervisor.send method }
     end
 
     # Public: Purge the RabbitMQ queue.
@@ -36,64 +35,19 @@ module Proletariat
 
     private
 
-    # Internal: Returns an open Bunny::Session object.
-    attr_reader :connection
-
-    # Internal: Returns the name of the RabbitMQ topic exchange.
-    attr_reader :exchange_name
-
     # Internal: Returns the Subscriber actor for this Manager.
     attr_reader :subscriber
 
-    # Internal: Returns the subclass of Worker used to process messages.
-    attr_reader :worker_class
-
-    # Internal: Returns the pool of initialized workers.
-    attr_reader :worker_pool
-
-    # Internal: Returns a shared mailbox for the pool of workers.
-    attr_reader :workers_mailbox
-
-    # Internal: Returns the number of worker threads in the worker pool.
-    attr_reader :worker_threads
-
-    # Internal: Assign a new Subscriber instance (configured for the current
-    #           worker type) to the manager's subscriber property.
-    #
-    # Returns nil.
-    def create_subscriber
-      @subscriber = Subscriber.new(
-        connection,
-        workers_mailbox,
-        generate_queue_config
-      )
-
-      nil
-    end
+    # Internal: The supervisor used to manage the Workers and Subscriber
+    attr_reader :supervisor
 
-    # Internal: Assign new Concurrent::Poolbox and Array[Worker] to the
-    #           manager's workers_mailbox and worker_pool properties
-    #           respectively.
+    # Internal: Builds a new QueueConfig from a given Worker subclass.
     #
-    # Returns nil.
-    def create_worker_pool
-      @workers_mailbox, @worker_pool = worker_class.pool(worker_threads)
-
-      nil
-    end
-
-    # Internal: Builds a new QueueConfig object passing in some settings from
-    #           worker_class.
+    # worker_class - The Worker subclass to base settings on.
     #
     # Returns a new QueueConfig instance.
-    def generate_queue_config
-      QueueConfig.new(
-        worker_class.name,
-        exchange_name,
-        worker_class.routing_keys,
-        worker_threads,
-        false
-      )
+    def generate_queue_config(worker_class)
+      QueueConfig.new(worker_class.name, worker_class.routing_keys, false)
     end
   end
 end

data/lib/proletariat/publisher.rb

@@ -1,87 +1,63 @@
+require 'proletariat/concerns/logging'
+
 module Proletariat
-  # Public: Listens for messages in it's mailbox and publishes
-  #         these to a RabbitMQ topic exchange.
-  class Publisher < Concurrent::Actor
+  # Public: Receives messages and publishes them to a RabbitMQ topic exchange.
+  class Publisher
     include Concerns::Logging
 
     # Public: Creates a new Publisher instance.
-    #
-    # connection    - An open Bunny::Session object.
-    # exchange_name - A String of the RabbitMQ topic exchange.
-    def initialize(connection, exchange_name)
-      @channel  = connection.create_channel
-      @exchange = channel.topic(exchange_name, durable: true)
+    def initialize
+      @channel  = Proletariat.connection.create_channel
+      @exchange = channel.topic(Proletariat.exchange_name, durable: true)
     end
 
-    # Public: Called by the Concurrent framework to handle new mailbox
-    #         messages. Overridden in this subclass to push messages to a
-    #         RabbitMQ topic exchange.
-    #
-    # 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.
+    # Public: Logs the 'online' status of the publisher.
     #
     # Returns nil.
-    def act(to, message)
-      publish(to, message)
+    def started
+      log_info 'Now online'
 
       nil
     end
 
-    # Public: Called by the Concurrent framework on actor start. Overridden in
-    #         this subclass to log the status of the publisher.
+    # Public: Logs the 'offline' status of the publisher.
     #
     # Returns nil.
-    def on_run
-      super
-      log_info 'Now online'
+    def stopped
+      log_info 'Now offline'
 
       nil
     end
 
-    # Public: Called by the Concurrent framework on actor stop. Overridden in
-    #         this subclass to log the status of the publisher.
-    def on_stop
+    # Public: Logs the 'shutting down' status of the publisher.
+    #
+    # Returns nil.
+    def stopping
       log_info 'Attempting graceful shutdown.'
-      wait_for_publish_queue unless queue.empty?
-
-      super
-
-      log_info 'Now offline'
 
       nil
     end
 
-    private
-
-    # Internal: Returns the Bunny::Channel in use.
-    attr_reader :channel
-
-    # Internal: Returns the Bunny::Exchange in use.
-    attr_reader :exchange
-
-    # Internal: Handles the actual message send to the exchange.
+    # Public: Push a message to a RabbitMQ topic exchange.
     #
-    # to      - The routing key.
+    # 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)
+    def work(to, message)
       exchange.publish message, routing_key: to, persistent: true
 
       nil
     end
 
-    # Internal: Blocks until each message has been published.
-    #
-    # Returns nil.
-    def wait_for_publish_queue
-      log_info 'Waiting for work queue to drain.'
+    private
 
-      publish(*queue.pop.message) until queue.empty?
+    # Internal: Returns the Bunny::Channel in use.
+    attr_reader :channel
 
-      nil
-    end
+    # Internal: Returns the Bunny::Exchange in use.
+    attr_reader :exchange
   end
 end

data/lib/proletariat/queue_config.rb

@@ -1,9 +1,5 @@
 # Internal: Value object to hold RabbitMQ settings.
-class QueueConfig < Struct.new(:worker_name,
-                               :exchange_name,
-                               :routing_keys,
-                               :prefetch,
-                               :auto_delete)
+class QueueConfig < Struct.new(:worker_name, :routing_keys, :auto_delete)
   # Public: Create an underscored RabbitMQ queue name from the worker_name.
   #
   # Examples

data/lib/proletariat/runner.rb

@@ -7,37 +7,16 @@ module Proletariat
     # Public: Delegate lifecycle calls to the supervisor.
     def_delegators :supervisor, :run, :run!, :stop, :running?
 
-    # Public: Returns an open Bunny::Session object.
-    attr_reader :connection
-
-    # Public: Returns the name of the RabbitMQ topic exchange.
-    attr_reader :exchange_name
-
-    # Public: Creates a new Runner instance. Default options should be fine for
-    #         most scenarios.
-    #
-    # options - A Hash of options (default: {}):
-    #             :connection        - An open RabbitMQ::Session object.
-    #             :exchange_name     - The RabbitMQ topic exchange name as a
-    #                                  String.
-    #             :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 initialize(options = {})
-      @connection        = options.fetch :connection, create_connection
-      @exchange_name     = options.fetch :exchange_name, DEFAULT_EXCHANGE_NAME
-      @publisher_threads = options.fetch :publisher_threads, 2
-      @supervisor        = options.fetch :supervisor, create_supervisor
-      @worker_classes    = options.fetch :worker_classes, []
-      @worker_threads    = options.fetch :worker_threads, 3
-
-      @managers = []
-
-      create_publisher_pool
+    # Public: Creates a new Runner instance.
+    def initialize
+      @supervisor = Supervisor.new
+      @managers   = Proletariat.worker_classes.map do |worker_class|
+        Manager.new(worker_class)
+      end
 
-      add_publishers_to_supervisor
-      add_workers_to_supervisor
+      supervisor.supervise_pool('publishers', Proletariat.publisher_threads,
+                                Publisher)
+      managers.each { |manager| supervisor.add_supervisor manager }
     end
 
     # Public: Publishes a message to RabbitMQ via the publisher pool.
@@ -49,7 +28,7 @@ module Proletariat
     #
     # Returns nil.
     def publish(to, message)
-      publishers_mailbox.post to, message
+      supervisor['publishers'].post to, message
 
       nil
     end
@@ -68,82 +47,7 @@ module Proletariat
     # Internal: Returns an Array of the currently supervised Managers.
     attr_reader :managers
 
-    # Internal: Returns the pool of initialized publishers.
-    attr_reader :publisher_pool
-
-    # Internal: Returns a shared mailbox for the pool of publishers.
-    attr_reader :publishers_mailbox
-
-    # Internal: Returns the number of publisher threads in the publisher pool.
-    attr_reader :publisher_threads
-
     # Internal: Returns the supervisor instance.
     attr_reader :supervisor
-
-    # Internal: Returns an Array of Worker subclasses.
-    attr_reader :worker_classes
-
-    # Internal: Returns the number of worker threads per manager.
-    attr_reader :worker_threads
-
-    # Internal: Adds each publisher in the publisher_pool to the supervisor.
-    #
-    # Returns nil.
-    def add_publishers_to_supervisor
-      publisher_pool.each { |publisher| supervisor.add_worker publisher }
-
-      nil
-    end
-
-    # Internal: Creates a Manager per worker_class and adds these to the
-    #           supervisor.
-    #
-    # Returns nil.
-    def add_workers_to_supervisor
-      worker_classes.each do |worker_class|
-        manager = create_manager(worker_class)
-        @managers << manager
-        supervisor.add_worker manager
-      end
-
-      nil
-    end
-
-    # Internal: Creates a new Bunny::Session and opens it.
-    #
-    # Returns an open Bunny::Session instance.
-    def create_connection
-      new_connection = Bunny.new
-      new_connection.start
-
-      new_connection
-    end
-
-    # Internal: Assign new Concurrent::Poolbox and Array[Publisher] to the
-    #           manager's publishers_mailbox and publisher_pool properties
-    #           respectively.
-    #
-    # Returns nil.
-    def create_publisher_pool
-      @publishers_mailbox, @publisher_pool = Publisher.pool(publisher_threads,
-                                                            connection,
-                                                            exchange_name)
-    end
-
-    # Internal: Creates a new Concurrent::Supervisor.
-    #
-    # Returns a Concurrent::Supervisor instance.
-    def create_supervisor
-      Concurrent::Supervisor.new
-    end
-
-    # Internal: Creates a Manager for a given Worker subclass adding relevant
-    #           arguments from Runner properties.
-    #
-    # Returns a Manager instance.
-    def create_manager(worker_class)
-      Manager.new(connection, exchange_name, worker_class,
-                  worker_threads: worker_threads)
-    end
   end
 end