rabbitmq-actors 2.0.0

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "rabbitmq/actors"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/rabbitmq/actors.rb

@@ -0,0 +1,13 @@
+require 'active_support'
+require 'active_support/core_ext'
+require 'active_support/concern'
+require 'bunny'
+require_relative 'server'
+require_relative 'actors/version'
+require_relative 'actors/patterns'
+require_relative 'actors/testing'
+
+module RabbitMQ
+  module Actors
+  end
+end

data/lib/rabbitmq/actors/base/agent.rb

@@ -0,0 +1,108 @@
+module RabbitMQ
+  module Actors
+    module Base
+
+      # The base class for RabbitMQ producers, workers, publishers, consumers...
+      # @abstract Subclass and override #pre_initialize and/or #post_initialize to define
+      #   actual agent classes.
+      #
+      # @example
+      #   module RabbitMQ
+      #     module Actors
+      #       module Base
+      #
+      #         class Producer < Agent
+      #           def post_initialize(queue_name:, opts = {})
+      #             set_reply_queue(opts[:reply_queue_name])
+      #           end
+      #
+      #           def publish(message, correlation_key: true)
+      #             options = { routing_key: queue.name, durable: durable }
+      #             options.merge!(reply_to: reply_queue.name)           if reply_queue
+      #             options.merge!(correlation_id: SecureRandom.hex(10)) if correlation_key
+      #             exchange.publish(message, options)
+      #           end
+      #
+      #           def close!
+      #             channel.close
+      #           end
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      class Agent
+        attr_reader :queue
+
+        # Instantiate a new agent.
+        # #pre_initialize and #post_initialize methods are called just at the beginning
+        # and end respectively.
+        # Redefine them in your subclass to complete your subclass initialization process.
+        #
+        # @option opts [String]  :queue_name the queue name to bind the agent with if any.
+        # @option opts [Boolean] :exclusive (true) if the queue can only be used by this agent and
+        #   removed when this agent's connection is closed.
+        # @option opts [Boolean] :auto_delete (true) if the queue will be deleted when
+        #   there are no more consumers subscribed to it.
+        # @option opts [Logger]  :logger  the logger where to output info about agent's activity.
+        # Rest of options required by your subclasses.
+        def initialize(**opts)
+          pre_initialize **opts
+          set_queue(opts[:queue_name], **opts) if opts[:queue_name]
+          set_logger(opts[:logger])
+          post_initialize **opts
+        end
+
+        private
+
+        # @!attribute [r] logger
+        # @return [Logger] the logger where to log agent's activity
+        attr_reader :logger
+
+        # The connection object to the RabbitMQ server.
+        # @return [Bunny::Session] the connection object.
+        def connection
+          @connection ||= Server.connection
+        end
+
+        # The channel where to send messages through
+        # @return [Bunny::Channel] the talking channel to RabbitMQ server.
+        def channel
+          @channel ||= connection.create_channel
+        end
+
+        # Method called just at the beginning of initializing an instance.
+        # Redefine it in your class to do the specific init you want.
+        # @param args [Array], list of params received in the initialize call.
+        def pre_initialize(*args)
+        end
+
+        # Method called just at the end of initializing an instance.
+        # Redefine it in your class to do the specific init you want.
+        # @param args [Array], list of params received in the initialize call.
+        def post_initialize(*args)
+        end
+
+        # Create/open a durable queue of the given name.
+        # @param name [String] name of the queue.
+        # @param opts [Hash] properties of the queue.
+        # @raise [Exception] if queue already set.
+        # @return [Bunny::Queue] the queue where to address/get messages.
+        def set_queue(name, **opts)
+          raise "Queue already set" if queue
+          auto_delete = opts.fetch(:auto_delete, true)
+          exclusive   = opts.fetch(:exclusive,   true)
+          @queue = channel.queue(name, durable: true, auto_delete: auto_delete, exclusive: exclusive)
+        end
+
+        # Set logger to output agent info.
+        # If logger is nil, STDOUT with a DEBUG level of severity is set up as logger.
+        # @param logger [Logger] where to address output info.
+        # @return [Logger] the logger instance where to output info.
+        def set_logger(logger)
+          @logger = logger || Logger.new(STDOUT)
+        end
+      end
+    end
+  end
+end

data/lib/rabbitmq/actors/base/consumer.rb

@@ -0,0 +1,105 @@
+require_relative 'agent'
+
+module RabbitMQ
+  module Actors
+    module Base
+
+      # The base class to define actual RabbitMQ message consumer classes.
+      # @abstract Subclass and override #perform to define actual consumer classes.
+      #
+      # @example
+      #   module RabbitMQ
+      #     module Actors
+      #       class Worker < Base::Consumer
+      #         def initialize(queue_name:, **opts)
+      #           super(opts.merge(queue_name: queue_name))
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      class Consumer < Agent
+        # @param :queue_name [String] the queue name to bind the consumer with.
+        # @option opts [Boolean] :manual_ack to tell RabbitMQ server not to remove the message from
+        #   re-delivery until a manual acknowledgment from the consumer has been received.
+        # @option opts [Proc] :on_cancellation to be executed if the agent is cancelled
+        # Rest of options required by your subclasses.
+        def initialize(queue_name: '', **opts)
+          super(opts.merge(queue_name: queue_name))
+        end
+
+        # Start listening to the queue and block waiting for a new task to be assigned by the server.
+        # Perform the task, acknowledge if required and keep listening waiting for the message to come.
+        # @raise [Exception] if something goes wrong during the execution of the task.
+        def start!
+          @_cancelled = false
+          channel.prefetch(1)
+          queue.subscribe(block: true, manual_ack: manual_ack?, on_cancellation: cancellation_handler) do |delivery_info, properties, body|
+            begin
+              logger.info(self.class.name) { "#{self} received task: #{body}" }
+              self.perform_result = perform(delivery_info: delivery_info, properties: properties, body: body)
+              done!(delivery_info)
+              logger.info(self.class.name) { "#{self} performed task!" }
+            rescue Exception => e
+              logger.error "Error when #{self} performing task: #{e.message}"
+              cancellation_handler.call
+              fail(e)
+            end
+          end
+          cancellation_handler.call
+          perform_result
+        end
+
+        private
+
+        # @!attribute [rw] perform_result
+        #   @return [Object] the result of execution of the last task received by the consumer
+        attr_accessor :perform_result
+
+        # @!attribute [r] manual_ack
+        #   @return [Boolean] whether to acknowledge execution of messages to the server
+        attr_reader   :manual_ack
+        alias_method  :manual_ack?, :manual_ack
+
+        # @!attribute [r] on_cancellation
+        #   @return [Proc] the proc to be executed before the consumer is finished.
+        attr_reader :on_cancellation
+
+        # Set manual_ack flag based on options received.
+        # Also set the code to execute before terminating the consumer.
+        # @see #initialize for the list of options that can be received.
+        def pre_initialize(**opts)
+          @manual_ack      = opts[:manual_ack].present?
+          @on_cancellation = opts[:on_cancellation] || ->{}
+        end
+
+        # Set the code to execute when the consumer is cancelled before exit.
+        # Execute the provided code and close the connection to RabbitMQ server.
+        # @return [Proc] handler to execute before exit.
+        def cancellation_handler
+          lambda do
+            if not @_cancelled
+              on_cancellation.call
+              connection.close
+              @_cancelled = true
+            end
+          end
+        end
+
+        # Perform the assigned task
+        # @param task [Hash] the properties of the message received.
+        # @raise [Exception] Override this method in your subclass.
+        def perform(**task)
+          raise "No work defined! for this task: #{task[:body]}. Define #perform private method in your class"
+        end
+
+        # Hook to be executed after the consumer completes an assigned task.
+        # Send acknowledgement to the channel if required
+        # @param delivery_info [Bunny Object] contains delivery info about the message to acknowledge.
+        def done!(delivery_info)
+          channel.ack(delivery_info.delivery_tag) if manual_ack?
+        end
+      end
+    end
+  end
+end

data/lib/rabbitmq/actors/base/producer.rb

@@ -0,0 +1,83 @@
+require_relative 'agent'
+
+module RabbitMQ
+  module Actors
+    module Base
+
+      # The base class to define actual RabbitMQ message producer classes.
+      # @abstract Subclass and override #pre_initialize and #exchange to define actual producer classes.
+      #
+      # @example
+      #   module RabbitMQ::Actors
+      #     class MasterProducer < Base::Producer
+      #       def initialize(queue_name:, **opts)
+      #         super(opts.merge(queue_name: queue_name))
+      #       end
+      #
+      #       def publish(message, message_id:, **opts)
+      #         super(message, opts.merge(message_id: message_id, routing_key: queue.name))
+      #       end
+      #
+      #       private
+      #
+      #       def exchange
+      #         @exchange ||= channel.default_exchange
+      #       end
+      #     end
+      #   end
+      #
+      class Producer < Agent
+        # Send a messages to RabbitMQ server.
+        # Log the action to the logger with info severity.
+        # @param message [String] the message body to be sent.
+        # @param :message_id [String] user-defined id for replies to refer to this message using :correlation_id
+        # @param :opts [Hash] receives extra options from your subclass
+        # @see Bunny::Exchange#publish for extra options
+        def publish(message, message_id:, **opts)
+          options = opts.merge(message_id: message_id).reverse_merge!(persistent: true)
+          options.merge!(reply_to: reply_queue.name) if reply_queue
+          logger.info(self.class.name) { "Just Before #{self} publishes message: #{message} with options: #{options}" }
+          exchange.publish(message, options)
+          logger.info(self.class.name) { "Just After #{self} publishes message: #{message} with options: #{options}" }
+          self
+        end
+
+        delegate :on_return, to: :exchange
+
+        # Close the connection channel to RabbitMQ.
+        # Log the action to the logger with info severity.
+        def close
+          logger.info(self.class.name) { "Just Before #{self} closes RabbitMQ channel!" }
+          channel.close
+          logger.info(self.class.name) { "Just After #{self} closes RabbitMQ channel!" }
+        end
+        alias_method :and_close, :close
+
+        private
+
+        attr_reader :reply_queue
+
+        # If opts[:reply_queue_name].present? set the queue where a consumer should reply.
+        # @see #initialize for the list of options that can be received.
+        def post_initialize(**opts)
+          set_reply_queue(opts[:reply_queue_name]) if opts[:reply_queue_name].present?
+        end
+
+        # The RabbitMQ exchange where to publish the message
+        # @raise [Exception] so it must be override in subclasses.
+        def exchange
+          raise "This is an abstract class. Override exchange method in descendant class"
+        end
+
+        # Set the RabbitMQ queue where a consumer should send replies.
+        # @param name [String] name of the queue.
+        # @raise [Exception] if reply_queue already set.
+        # @return [Bunny::Queue]
+        def set_reply_queue(name)
+          raise "Reply Queue already set" if reply_queue
+          @reply_queue = channel.queue(name, durable: true, auto_delete: true, exclusive: false)
+        end
+      end
+    end
+  end
+end

data/lib/rabbitmq/actors/patterns.rb

@@ -0,0 +1,10 @@
+require_relative 'patterns/master_workers/master_producer'
+require_relative 'patterns/master_workers/worker'
+require_relative 'patterns/publish_subscribe/publisher'
+require_relative 'patterns/publish_subscribe/subscriber'
+require_relative 'patterns/routing/routing_producer'
+require_relative 'patterns/routing/routing_consumer'
+require_relative 'patterns/topics/topic_producer'
+require_relative 'patterns/topics/topic_consumer'
+require_relative 'patterns/headers/headers_producer'
+require_relative 'patterns/headers/headers_consumer'

data/lib/rabbitmq/actors/patterns/headers/headers_consumer.rb

@@ -0,0 +1,106 @@
+require_relative '../../base/consumer'
+
+module RabbitMQ
+  module Actors
+    # A consumer of messages from RabbitMQ based on exchange and message headers matching.
+    # @abstract Subclass and override #perform to define your customized headers worker class.
+    #
+    # @example
+    #   class NewYorkBranchListener < RabbitMQ::Actors::HeadersConsumer
+    #     def initialize
+    #       super(headers_name:    'reports',
+    #             binding_headers: { 'type' => :econony, 'area' => 'Usa', 'x-match' => 'any' },
+    #             logger:          Rails.logger,
+    #             on_cancellation: ->{ ActiveRecord::Base.connection.close })
+    #     end
+    #
+    #     private
+    #
+    #     def perform(**task)
+    #       report_data = JSON.parse(task[:body])
+    #       process_report(report_data)
+    #     end
+    #
+    #     def process_report(data)
+    #       ...
+    #     end
+    #   end
+    #
+    #   class LondonBranchListener < RabbitMQ::Actors::HeadersConsumer
+    #     def initialize
+    #       super(headers_name:    'reports',
+    #             binding_headers: { 'type' => :industry, 'area' => 'Europe', 'x-match' =>'any' },
+    #             logger:          Rails.logger,
+    #             on_cancellation: ->{ ActiveRecord::Base.connection.close })
+    #     end
+    #
+    #     private
+    #
+    #     def perform(**task)
+    #       report_data = JSON.parse(task[:body])
+    #       process_report(report_data)
+    #     end
+    #
+    #     def process_report(data)
+    #       ...
+    #     end
+    #   end
+    #
+    #   RabbitMQ::Server.url = 'amqp://localhost'
+    #
+    #   NewYorkBranchListener.new.start!
+    #   LondonBranchListener.new.start!
+    #
+    class HeadersConsumer < Base::Consumer
+      # @!attribute [r] headers_name
+      #   @return [Bunny::Exchange] the headers exchange where to get messages from.
+      attr_reader :headers_name
+
+      # @!attribute [r] binding_headers
+      #   @return [Hash] the headers this worker is interested in.
+      #     The header 'x-match' MUST be included with value
+      #     'any' (match if any message header value matches) or
+      #     'all' (all message header values must match)
+      attr_reader :binding_headers
+
+      # @param :headers_name [String] name of the headers exchange this worker will receive messages.
+      # @param :binding_headers [Hash] headers this worker is interested in.
+      #   Default to all: '#'
+      # @option opts [Proc] :on_cancellation to be executed before the worker is terminated
+      # @option opts [Logger] :logger the logger where to output info about this agent's activity.
+      # Rest of options required by your subclass.
+      def initialize(headers_name:, binding_headers:, **opts)
+        super(opts.merge(headers_name: headers_name, binding_headers: binding_headers))
+      end
+
+      private
+
+      # Set headers exchange_name and binding_headers this worker is bound to.
+      # @see #initialize for the list of options that can be received.
+      def pre_initialize(**opts)
+        @headers_name    = opts[:headers_name]
+        @binding_headers = opts[:binding_headers]
+        super
+      end
+
+      # Bind this worker's queue to the headers exchange and to the given binding_key patterns
+      # @see #initialize for the list of options that can be received.
+      def post_initialize(**opts)
+        bind_queue_to_exchange_routing_keys
+        super
+      end
+
+      # The durable RabbitMQ headers exchange from where messages are received
+      # @return [Bunny::Exchange]
+      def exchange
+        @exchange ||= channel.headers(headers_name, durable: true)
+      end
+
+      # Bind this worker's listening queue to the headers exchange and receive only messages with headers
+      # matching all/any of the ones in binding_headers.
+      def bind_queue_to_exchange_routing_keys
+        queue.bind(exchange, arguments: binding_headers)
+      end
+    end
+  end
+end