synapse-core 0.4.0 → 0.5.1

data/lib/synapse/command/async_command_bus.rb

@@ -0,0 +1,41 @@
+require 'thread/pool'
+
+module Synapse
+  module Command
+    # Command bus that uses a thread pool to asynchronously execute commands, invoking the given
+    # callback when execution is completed or resulted in an error
+    #
+    # @todo Look into non-blocking circular buffers or LMAX Disruptor
+    class AsynchronousCommandBus < SimpleCommandBus
+      # Pool of dispatching threads backed by a queue
+      # @return [Thread::Pool]
+      attr_accessor :thread_pool
+
+      # @api public
+      # @param [CommandMessage] command
+      # @param [CommandCallback] callback
+      # @return [undefined]
+      def dispatch_with_callback(command, callback)
+        @thread_pool.process do
+          super command, callback
+        end
+      end
+
+      # Shuts down the command bus, waiting until all tasks are finished
+      #
+      # @api public
+      # @return [undefined]
+      def shutdown
+        @thread_pool.shutdown
+      end
+
+      # Shuts down the command bus without waiting for tasks to finish
+      #
+      # @api public
+      # @return [undefined]
+      def shutdown!
+        @thread_pool.shutdown!
+      end
+    end # AsynchronousCommandBus
+  end # Command
+end

data/lib/synapse/command/command_callback.rb

@@ -13,6 +13,53 @@ module Synapse
       # @param [Exception] exception The cause of the failure
       # @return [undefined]
       def on_failure(exception); end
-    end
-  end
+    end # CommandCallback
+
+    # Callback that provides a deferred result or exception from the execution of a command
+    class FutureCallback < CommandCallback
+      def initialize
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+      end
+
+      # @raise [Exception] If an exception occured during command execution
+      # @param [Float] timeout
+      # @return [Object] The result from the command handler
+      def result(timeout = nil)
+        @mutex.synchronize do
+          unless @dispatched
+            @condition.wait @mutex, timeout
+          end
+
+          if @exception
+            raise @exception
+          end
+
+          @result
+        end
+      end
+
+      # @param [Object] result The result from the command handler
+      # @return [undefined]
+      def on_success(result)
+        @mutex.synchronize do
+          @dispatched = true
+          @result = result
+
+          @condition.broadcast
+        end
+      end
+
+      # @param [Exception] exception The cause of the failure
+      # @return [undefined]
+      def on_failure(exception)
+        @mutex.synchronize do
+          @dispatched = true
+          @exception = exception
+
+          @condition.broadcast
+        end
+      end
+    end # FutureCallback
+  end # Command
 end

data/lib/synapse/command/command_handler.rb

@@ -1,6 +1,8 @@
 module Synapse
   module Command
     # Mixin for an object capable of handling commands
+    #
+    # Consider using the command handler mixin that uses message wiring.
     module CommandHandler
       # Handles the given command
       #

data/lib/synapse/command/filters/validation.rb

@@ -15,7 +15,7 @@ module Synapse
 
         command
       end
-    end
+    end # ActiveModelValidationFilter
 
     # Raised when a command with ActiveModel doesn't pass validation
     class ActiveModelValidationError < CommandValidationError
@@ -27,6 +27,6 @@ module Synapse
       def initialize(errors)
         @errors = errors
       end
-    end
+    end # ActiveModelValidationError
   end
 end

data/lib/synapse/command/gateway/interval_retry_scheduler.rb

@@ -0,0 +1,75 @@
+module Synapse
+  module Command
+    # Implementation of a retry scheduler that retries commands at regular intervals
+    #
+    # If the last failure is explicitly non-transient exception or the number of failures reaches
+    # the maximum number of retries, the command will not be scheduled for retry.
+    #
+    # This implementation uses EventMachine to schedule one-shot timers.
+    class IntervalRetryScheduler < RetryScheduler
+      # @param [Float] interval
+      # @param [Integer] maxRetries
+      # @return [undefined]
+      def initialize(interval, maxRetries)
+        @interval = interval
+        @maxRetries = maxRetries
+
+        @logger = Logging.logger[self.class]
+      end
+
+      # @param [CommandMessage] command
+      # @param [Array] failures
+      # @param [Proc] dispatcher
+      # @return [Boolean]
+      def schedule(command, failures, dispatcher)
+        lastFailure = failures.last
+
+        if explicitly_non_transient? lastFailure
+          @logger.info 'Dispatch of command [%s] [%s] resulted in non-transient exception' %
+            [command.payload_type, command.id]
+
+          return false
+        end
+
+        failureCount = failures.size
+
+        if failureCount > @maxRetries
+          @logger.info 'Dispatch of command [%s] [%s] resulted in exception [%s] times' %
+            [command.payload_type, command.id, failureCount]
+
+          return false
+        end
+
+        if @logger.info?
+          @logger.info 'Dispatch of command [%s] [%s] resulted in exception; will retry up to [%s] more times' %
+            [command.payload_type, command.id, @maxRetries - failureCount]
+        end
+
+        perform_schedule command, dispatcher
+
+        true
+      end
+
+    private
+
+      # @param [Exception] exception
+      # @return [Boolean]
+      def explicitly_non_transient?(exception)
+        return true if exception.is_a? NonTransientError
+
+        if exception.respond_to? :cause
+          explicitly_non_transient? exception.cause
+        else
+          false
+        end
+      end
+
+      # @param [CommandMessage] command
+      # @param [Proc] dispatcher
+      # @return [undefined]
+      def perform_schedule(command, dispatcher)
+        EventMachine.add_timer @interval, &dispatcher
+      end
+    end # IntervalRetryScheduler
+  end # Command
+end

data/lib/synapse/command/gateway/retry_scheduler.rb

@@ -0,0 +1,26 @@
+module Synapse
+  module Command
+    # Represents a mechanism that decides whether or not to dispatch a command when previous
+    # attempts resulted in an exception being raised.
+    #
+    # @abstract
+    class RetryScheduler
+      # Inspects the given command message that failed due to an exception
+      #
+      # The given list of failures contains exceptions that have occured each time the command
+      # was dispatched by the command bus. It includes the most recent failure at the end of
+      # the list.
+      #
+      # The return value of this method indicates whether or not the command has been scheduled
+      # for a retry. If it has, the callback for the command should not be invoked. Otherwise,
+      # the failure will be interpreted as terminal and the callback will be invoked with the
+      # last recorded failure.
+      #
+      # @param [CommandMessage] command
+      # @param [Array] failures
+      # @param [Proc] dispatcher
+      # @return [Boolean]
+      def schedule(command, failures, dispatcher); end
+    end
+  end
+end

data/lib/synapse/command/gateway/retrying_callback.rb

@@ -0,0 +1,46 @@
+module Synapse
+  module Command
+    # Implementation of a callback that will retry the dispatch of a command if execution results
+    # in an exception
+    #
+    # This callback is not meant to be used directly. Use a command gateway implementation instead.
+    class RetryingCallback < CommandCallback
+      # @param [CommandCallback] delegate
+      # @param [CommandMessage] command
+      # @param [RetryScheduler] retry_scheduler
+      # @param [CommandBus] command_bus
+      # @return [undefined]
+      def initialize(delegate, command, retry_scheduler, command_bus)
+        @command = command
+        @delegate = delegate
+        @retry_scheduler = retry_scheduler
+
+        @failures = Array.new
+        @dispatcher = proc do
+          command_bus.dispatch_with_callback command, self
+        end
+      end
+
+      # @param [Object] result The result from the command handler
+      # @return [undefined]
+      def on_success(result)
+        @delegate.on_success result
+      end
+
+      # @param [Exception] exception The cause of the failure
+      # @return [undefined]
+      def on_failure(exception)
+        @failures.push exception
+
+        begin
+          unless exception.is_a? RuntimeError and
+              @retry_scheduler.schedule @command, @failures, @dispatcher
+            @delegate.on_failure exception
+          end
+        rescue
+          @delegate.on_failure $!
+        end
+      end
+    end # RetryingCallback
+  end # Command
+end

data/lib/synapse/command/gateway.rb

@@ -1,34 +1,79 @@
 module Synapse
   module Command
     # Simplified interface to the command bus
+    # @api public
     class CommandGateway
+      # @return [Array]
+      attr_reader :filters
+
+      # @return [RetryScheduler]
+      attr_accessor :retry_scheduler
+
       # @param [CommandBus] command_bus
       # @return [undefined]
       def initialize(command_bus)
         @command_bus = command_bus
+        @filters = Array.new
       end
 
       # Fire and forget method of sending a command to the command bus
       #
+      # If the given command is a bare object, it will be wrapped in a command message before
+      # being dispatched on the command bus.
+      #
+      # @api public
       # @param [Object] command
       # @return [undefined]
       def send(command)
-        @command_bus.dispatch(as_command_message(command))
+        send_with_callback command, CommandCallback.new
       end
 
-    private
-
+      # Sends the given command
+      #
+      # If the given command is a bare object, it will be wrapped in a command message before
+      # being dispatched on the command bus.
+      #
+      # @api public
       # @param [Object] command
-      # @return [CommandMessage]
-      def as_command_message(command)
-        unless command.is_a? CommandMessage
-          command = CommandMessage.build do |builder|
-            builder.payload = command
-          end
+      # @param [CommandCallback] callback
+      # @return [undefined]
+      def send_with_callback(command, callback)
+        command = process_with_filters(CommandMessage.as_message(command))
+
+        if @retry_scheduler
+          callback = RetryingCallback.new callback, command, @retry_scheduler, @command_bus
         end
 
+        @command_bus.dispatch_with_callback(command, callback)
+      end
+
+      # Sends the given command and blocks indefinitely until the result of the execution is
+      # provided, the timeout is created or the thread is interrupted.
+      #
+      # If the given command is a bare object, it will be wrapped in a command message before
+      # being dispatched on the command bus.
+      #
+      # @api public
+      # @raise [CommandExecutionError] If an error occured while executing the command
+      # @param [Object] command
+      # @param [Float] timeout
+      # @return [Object] The return value from the command handler
+      def send_and_wait(command, timeout = nil)
+        callback = FutureCallback.new
+        send_with_callback command, callback
+        callback.result timeout
+      end
+
+    protected
+
+      # @param [CommandMessage] command
+      # @return [CommandMessage] The message to dispatch
+      def process_with_filters(command)
+        @filters.each do |filter|
+          command = filter.filter command
+        end
         command
       end
-    end
-  end
+    end # CommandGateway
+  end # Command
 end

data/lib/synapse/command/interceptor_chain.rb

@@ -26,6 +26,6 @@ module Synapse
           @handler.handle command, @unit
         end
       end
-    end
-  end
+    end # InterceptorChain
+  end # Command
 end

data/lib/synapse/command/interceptors/serialization.rb

@@ -16,7 +16,7 @@ module Synapse
         unit.register_listener @listener
         chain.proceed command
       end
-    end
+    end # SerializationOptimizingInterceptor
 
     # @api private
     class SerializationOptimizingListener < UnitOfWork::UnitOfWorkListener
@@ -30,6 +30,6 @@ module Synapse
           Serialization::SerializationAwareEventMessage.decorate event
         end
       end
-    end
+    end # SerializationOptimizingListener
   end
 end

data/lib/synapse/command/message.rb

@@ -6,6 +6,22 @@ module Synapse
       def self.builder
         CommandMessageBuilder
       end
+
+      # Creates a command message using the given command object
+      #
+      # If the given object is an command message, it will be returned unchanged.
+      #
+      # @param [Object] command
+      # @return [CommandMessage]
+      def self.as_message(command)
+        unless command.is_a? CommandMessage
+          command = self.build do |builder|
+            builder.payload = command
+          end
+        end
+
+        command
+      end
     end
 
     # Message builder capable of producing CommandMessage instances

data/lib/synapse/command/simple_command_bus.rb

@@ -23,12 +23,14 @@ module Synapse
         @unit_factory = unit_factory
       end
 
+      # @api public
       # @param [CommandMessage] command
       # @return [undefined]
       def dispatch(command)
         dispatch_with_callback command, CommandCallback.new
       end
 
+      # @api public
       # @param [CommandMessage] command
       # @param [CommandCallback] callback
       # @return [undefined]
@@ -45,6 +47,7 @@ module Synapse
         end
       end
 
+      # @api public
       # @param [Class] command_type
       # @param [CommandHandler] handler
       # @return [undefined]
@@ -61,6 +64,7 @@ module Synapse
         @handlers.store command_type, handler
       end
 
+      # @api public
       # @param [Class] command_type
       # @param [CommandHandler] handler
       # @return [undefined]
@@ -133,6 +137,6 @@ module Synapse
           raise NoHandlerError, 'No handler subscribed for command [%s]' % type
         end
       end
-    end
-  end
+    end # SimpleCommandBus
+  end # Command
 end

data/lib/synapse/command/wiring.rb

@@ -14,7 +14,7 @@ module Synapse
       # @param [UnitOfWork] current_unit Current unit of work
       # @return [Object] The result of handling the given command
       def handle(command, current_unit)
-        wire = self.wire_registry.wire_for command.payload_type
+        wire = wire_registry.wire_for command.payload_type
 
         unless wire
           raise ArgumentError, 'Not capable of handling [%s] commands' % command.payload_type
@@ -42,6 +42,6 @@ module Synapse
           command_bus.unsubscribe type, self
         end
       end
-    end
-  end
+    end # WiringCommandHandler
+  end # Command
 end

data/lib/synapse/command.rb

@@ -2,6 +2,8 @@ module Synapse
   module Command
     extend ActiveSupport::Autoload
 
+    autoload :AsynchronousCommandBus, 'synapse/command/async_command_bus'
+
     # Optional filters and interceptors
     autoload_at 'synapse/command/duplication' do
       autoload :DuplicationFilter
@@ -26,9 +28,13 @@ require 'synapse/command/command_filter'
 require 'synapse/command/command_handler'
 require 'synapse/command/dispatch_interceptor'
 require 'synapse/command/errors'
-require 'synapse/command/gateway'
 require 'synapse/command/interceptor_chain'
 require 'synapse/command/message'
 require 'synapse/command/rollback_policy'
 require 'synapse/command/simple_command_bus'
 require 'synapse/command/wiring'
+
+require 'synapse/command/gateway'
+require 'synapse/command/gateway/retry_scheduler'
+require 'synapse/command/gateway/interval_retry_scheduler'
+require 'synapse/command/gateway/retrying_callback'

data/lib/synapse/common/concurrency/identifier_lock.rb

@@ -1,4 +1,5 @@
 module Synapse
+  # Generic implementation of a lock that can be used to lock an identifier for use
   # @todo Deadlock detection
   class IdentifierLock
     # @return [undefined]
@@ -34,7 +35,6 @@ module Synapse
       end
 
       lock_for(identifier).unlock
-      dispose_if_unused(identifier)
     end
 
   private
@@ -52,20 +52,5 @@ module Synapse
     def lock_available?(identifier)
       @identifiers.has_key? identifier
     end
-
-    # Disposes of the lock for the given identifier if it has no threads waiting for it
-    #
-    # @param [String] identifier
-    # @return [undefined]
-    def dispose_if_unused(identifier)
-      lock = lock_for identifier
-      if lock.try_lock
-        @lock.synchronize do
-          @identifiers.delete identifier
-        end
-
-        lock.unlock
-      end
-    end
   end # IdentifierLock
-end # Synapse
+end

data/lib/synapse/common/concurrency/public_lock.rb

@@ -1,6 +1,5 @@
-require 'monitor'
-
 module Synapse
+  # Lock that tracks the thread owning the lock and any waiting threads
   class PublicLock
     # @return [Thread] The current owner of the thread, if any
     attr_reader :owner
@@ -11,7 +10,6 @@ module Synapse
     # @return [undefined]
     def initialize
       @mutex = Mutex.new
-      @condition = ConditionVariable.new
       @waiting = Array.new
     end
 
@@ -50,9 +48,10 @@ module Synapse
         end
 
         while @owner
+          @waiting.push Thread.current
+
           begin
-            @waiting.push Thread.current
-            @condition.wait @mutex
+            @mutex.sleep
           ensure
             @waiting.delete Thread.current
           end
@@ -68,7 +67,9 @@ module Synapse
       @mutex.synchronize do
         if @owner == Thread.current
           @owner = nil
-          @condition.signal
+
+          first_waiter = @waiting.first
+          first_waiter.wakeup if first_waiter
         else
           raise ThreadError, 'Lock is not owned by the current thread'
         end
@@ -83,9 +84,7 @@ module Synapse
           raise ThreadError, 'Lock is already owned by the current thread'
         end
 
-        if @owner
-          return false
-        end
+        return false if @owner
 
         @owner = Thread.current
       end

data/lib/synapse/common/errors.rb

@@ -5,7 +5,7 @@ module Synapse
   # Raised when an error has occured that resulted from misconfiguration
   class ConfigurationError < SynapseError; end
 
-  # Raised when an error has occured that cannot be resolved with intervention
+  # Raised when an error has occured that cannot be resolved without intervention
   class NonTransientError < SynapseError; end
 
   # Raised when an error has occured that might be resolved by retrying the operation

data/lib/synapse/common/message.rb

@@ -47,9 +47,7 @@ module Synapse
     # @param [Hash] additional_metadata
     # @return [Message]
     def and_metadata(additional_metadata)
-      if additional_metadata.empty?
-        return self
-      end
+      return self if additional_metadata.empty?
 
       builder = self.class.builder.new
       build_duplicate builder, @metadata.merge(additional_metadata)
@@ -61,9 +59,7 @@ module Synapse
     # @param [Hash] replacement_metadata
     # @return [Message]
     def with_metadata(replacement_metadata)
-      if @metadata == replacement_metadata
-        return self
-      end
+      return self if @metadata == replacement_metadata
 
       builder = self.class.builder.new
       build_duplicate builder, replacement_metadata

data/lib/synapse/common.rb

@@ -0,0 +1,9 @@
+require 'synapse/common/errors'
+require 'synapse/common/identifier'
+require 'synapse/common/message'
+require 'synapse/common/message_builder'
+
+require 'synapse/common/concurrency/identifier_lock'
+require 'synapse/common/concurrency/public_lock'
+
+require 'synapse/common/duplication'

data/lib/synapse/configuration/component/command_bus/async_command_bus.rb

@@ -0,0 +1,41 @@
+module Synapse
+  module Configuration
+    # Definition builder used to build an asynchronous command bus
+    #
+    # @see SimpleCommandBusDefinitionBuilder For additional options
+    #
+    # @example The minimum possible effort to build an asynchronous command bus
+    #   async_command_bus
+    #
+    # @example Create an asynchronous command bus with a custom thread count
+    #   async_command_bus do
+    #     use_threads 8, 12
+    #   end
+    class AsynchronousCommandBusDefinitionBuilder < SimpleCommandBusDefinitionBuilder
+      # @param [Integer] min_threads
+      # @param [Integer] max_threads
+      # @return [undefined]
+      def use_threads(min_threads, max_threads = nil)
+        @min_threads = min_threads
+        @max_threads = max_threads
+      end
+
+    protected
+
+      # @return [undefined]
+      def populate_defaults
+        super
+        use_threads 4
+      end
+
+      # @param [UnitOfWorkFactory] unit_factory
+      # @return [AsynchronousCommandBus]
+      def create_command_bus(unit_factory)
+        command_bus = Command::AsynchronousCommandBus.new unit_factory
+        command_bus.thread_pool = Thread.pool @min_threads, @max_threads
+
+        command_bus
+      end
+    end # AsynchronousCommandBusDefinitionBuilder
+  end # Configuration
+end