synapse-core 0.4.0 → 0.5.1

data/lib/synapse/serialization/serializer/oj.rb

@@ -29,6 +29,6 @@ module Synapse
       def native_content_type
         String
       end
-    end
-  end
+    end # OjSerializer
+  end # Serialization
 end

data/lib/synapse/serialization/serializer/ox.rb

@@ -26,6 +26,6 @@ module Synapse
       def native_content_type
         String
       end
-    end
-  end
+    end # OxSerializer
+  end # Serialization
 end

data/lib/synapse/serialization/serializer.rb

@@ -95,6 +95,6 @@ module Synapse
       def convert(original, source_type, target_type)
         converter_factory.converter(source_type, target_type).convert_content(original)
       end
-    end
-  end
+    end # Serializer
+  end # Serialization
 end

data/lib/synapse/uow/factory.rb

@@ -23,6 +23,6 @@ module Synapse
           unit.start
         end
       end
-    end
-  end
+    end # UnitOfWorkFactory
+  end # UnitOfWork
 end

data/lib/synapse/uow/listener_collection.rb

@@ -146,6 +146,6 @@ module Synapse
 
         @logger.debug 'Listeners successfully notified'
       end
-    end
-  end
+    end # UnitOfWorkListenerCollection
+  end # UnitOfWork
 end

data/lib/synapse/uow/nesting.rb

@@ -26,6 +26,7 @@ module Synapse
       # resources it acquired. The effectively means that a rollback is done if the unit of work
       # failed to commit.
       #
+      # @api public
       # @raise [RuntimeError] If unit of work hasn't been started yet
       # @return [undefined]
       def commit
@@ -61,6 +62,7 @@ module Synapse
       # Any buffered events and registered aggregates are discarded and any registered unit of work
       # listeners are notified of the rollback.
       #
+      # @api public
       # @param [Error] cause
       # @return [undefined]
       def rollback(cause = nil)
@@ -79,6 +81,7 @@ module Synapse
 
       # Starts the unit of work, preparing it for aggregate registration
       #
+      # @api public
       # @raise [RuntimeError] If unit of work has already been started
       # @return [undefined]
       def start
@@ -105,6 +108,8 @@ module Synapse
       end
 
       # Returns true if this unit of work has been started
+      #
+      # @api public
       # @return [Boolean]
       def started?
         @started
@@ -224,6 +229,8 @@ module Synapse
 
     # Listener that allows a nested unit of work to properly operate within in a unit of
     # work that is not aware of nesting
+    #
+    # @api private
     class OuterCommitUnitOfWorkListener < UnitOfWorkListener
       # @param [UnitOfWork] inner_unit
       # @param [UnitOfWorkProvider] provider
@@ -257,6 +264,6 @@ module Synapse
       def on_cleanup(outer_unit)
         @inner_unit.perform_cleanup
       end
-    end
-  end
+    end # NestableUnitOfWork
+  end # UnitOfWork
 end

data/lib/synapse/uow/provider.rb

@@ -66,6 +66,6 @@ module Synapse
       rescue KeyError
         @threads.store Thread.current, Array.new
       end
-    end
-  end
+    end # UnitOfWorkProvider
+  end # UnitOfWork
 end

data/lib/synapse/uow/uow.rb

@@ -13,6 +13,8 @@ module Synapse
       end
 
       # Returns true if this unit of work is bound to a transaction
+      #
+      # @api public
       # @return [Boolean]
       def transactional?
         !!@transaction_manager
@@ -20,6 +22,7 @@ module Synapse
 
       # Registers a listener that is notified of state changes in this unit of work
       #
+      # @api public
       # @param [UnitOfWorkListener] listener
       # @return [undefined]
       def register_listener(listener)
@@ -38,6 +41,7 @@ module Synapse
       # and with the same identifier, that aggregate will be returned instead of the given
       # aggregate.
       #
+      # @api public
       # @param [AggregateRoot] aggregate
       # @param [EventBus] event_bus
       # @param [StorageListener] storage_listener
@@ -60,6 +64,7 @@ module Synapse
       # Buffers an event for publication to the given event bus until this unit of work is
       # committed
       #
+      # @api public
       # @param [EventMessage] event
       # @param [EventBus] event_bus
       # @return [EventMessage] The event that will be published to the event bus
@@ -78,6 +83,7 @@ module Synapse
 
       # Sets the transaction manager that will be used by this unit of work
       #
+      # @api public
       # @raise [RuntimeError] If unit of work has been started
       # @param [TransactionManager] transaction_manager
       # @return [undefined]
@@ -173,6 +179,6 @@ module Synapse
           end
         end
       end
-    end
-  end
+    end # UnitOfWork
+  end # UnitOfWork
 end

data/lib/synapse/upcasting.rb

@@ -1,5 +1,5 @@
 require 'synapse/upcasting/context'
-require 'synapse/upcasting/chain'
 require 'synapse/upcasting/data'
+require 'synapse/upcasting/upcaster_chain'
 require 'synapse/upcasting/upcaster'
 require 'synapse/upcasting/single_upcaster'

data/lib/synapse/version.rb

@@ -1,3 +1,3 @@
 module Synapse
-  VERSION = '0.4.0'
+  VERSION = '0.5.1'
 end

data/lib/synapse/wiring/message_wiring.rb

@@ -1,6 +1,10 @@
 module Synapse
   module Wiring
     # Base mixin that make it easier to wire handlers to their respective types
+    #
+    # It is recommended to use mixins more specific to the component being implemented, like
+    # wiring command handlers, event listeners, event-sourced members, or processes.
+    #
     # @abstract
     module MessageWiring
       extend ActiveSupport::Concern
@@ -14,6 +18,33 @@ module Synapse
       end
 
       module ClassMethods
+        # Wires a message handler to messages with payload of the given type
+        #
+        # @example
+        #   wire CashWithdrawnEvent do |event|
+        #     # do something with the event
+        #   end
+        #
+        # @example
+        #   wire CashWithdrawnEvent :to => :on_withdraw
+        #
+        #   def on_withdraw(event)
+        #     # do something with the event
+        #   end
+        #
+        # Certain components that use message handling have different options that can be set
+        # on wires, like wiring processes.
+        #
+        # @example
+        #   wire SellTransactionStartedEvent, :start => true, :correlate => :transaction_id do
+        #     # do something with the event
+        #   end
+        #
+        # @api public
+        # @param [Class] type
+        # @param [Object...] args
+        # @param [Proc] block
+        # @return [undefined]
         def wire(type, *args, &block)
           options = args.extract_options!
 

data/lib/synapse.rb

@@ -3,24 +3,12 @@ require 'active_support/core_ext'
 require 'logging'
 require 'set'
 
+require 'synapse/common'
 require 'synapse/version'
 
-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'
-
 module Synapse
   extend ActiveSupport::Autoload
 
-  autoload_at 'synapse/common/duplication' do
-    autoload :DuplicationError
-    autoload :DuplicationRecorder
-  end
-
   eager_autoload do
     # Common components
     autoload :Command
@@ -34,9 +22,9 @@ module Synapse
 
   # Optional components
   autoload :Auditing
+  autoload :Configuration
   autoload :EventSourcing
   autoload :EventStore
-  autoload :Partitioning
   autoload :ProcessManager
   autoload :Upcasting
 end

data/test/auditing/data_provider_test.rb

@@ -4,7 +4,7 @@ module Synapse
   module Auditing
 
     class CommandMetadataProviderTest < Test::Unit::TestCase
-      def test_provide_data_for
+      should 'provide the metadata from a command for auditing' do
         data = { foo: 0 }
 
         provider = CommandMetadataProvider.new
@@ -17,7 +17,7 @@ module Synapse
     end
 
     class CorrelationDataProviderTest < Test::Unit::TestCase
-      def test_provide_data_for
+      should 'provide the identifier of a command for auditing' do
         provider = CorrelationDataProvider.new
         command = Command::CommandMessage.build
 

data/test/auditing/dispatch_interceptor_test.rb

@@ -4,7 +4,7 @@ module Synapse
   module Auditing
 
     class AuditingDispatchInterceptorTest < Test::Unit::TestCase
-      def test_intercept
+      should 'register a unit of work listener for auditing' do
         return_value = Object.new
         chain = Object.new
         command = Object.new

data/test/auditing/unit_listener_test.rb

@@ -4,7 +4,7 @@ module Synapse
   module Auditing
 
     class AuditingUnitOfWorkListenerTest < Test::Unit::TestCase
-      def test_on_event_registered
+      should 'supplement events with auditing data' do
         data_provider_a = Object.new
         data_provider_b = Object.new
 
@@ -30,7 +30,7 @@ module Synapse
         assert listener.recorded_events.include? event
       end
 
-      def test_after_commit
+      should 'notify the audit logger of success after the unit of work is committed' do
         logger = Object.new
 
         command = Object.new
@@ -48,7 +48,7 @@ module Synapse
         listener.after_commit Object.new
       end
 
-      def test_on_rollback
+      should 'notify the audit logger of failure when a unit of work is rolled back' do
         logger = Object.new
 
         command = Object.new

data/test/command/async_command_bus_test.rb

@@ -0,0 +1,49 @@
+require 'test_helper'
+require 'support/countdown_latch'
+
+module Synapse
+  module Command
+    class AsynchronousCommandBusTest < Test::Unit::TestCase
+      def setup
+        unit_provider = UnitOfWork::UnitOfWorkProvider.new
+        unit_factory = UnitOfWork::UnitOfWorkFactory.new unit_provider
+
+        @bus = AsynchronousCommandBus.new unit_factory
+        @bus.thread_pool = Thread.pool 2
+      end
+
+      should 'be able to dispatch commands asynchronously using a thread pool' do
+        x = 5 # Number of commands to dispatch
+
+        command = CommandMessage.as_message TestCommand.new
+        handler = TestAsyncHandler.new x
+
+        @bus.subscribe TestCommand, handler
+
+        x.times do
+          @bus.dispatch command
+        end
+
+        wait_until do
+          handler.latch.count == 0
+        end
+
+        @bus.shutdown
+      end
+    end
+
+    class TestAsyncHandler
+      attr_reader :latch
+
+      def initialize(x)
+        @latch = CountdownLatch.new x
+      end
+
+      def handle(command, unit)
+        @latch.countdown!
+      end
+    end
+
+    class TestCommand; end
+  end
+end

data/test/command/duplication_test.rb

@@ -3,7 +3,7 @@ require 'test_helper'
 module Synapse
   module Command
     class DuplicationFilterTest < Test::Unit::TestCase
-      def test_filter
+      should 'record commands so that duplication can be detected' do
         recorder = DuplicationRecorder.new
         filter = DuplicationFilter.new recorder
 
@@ -17,7 +17,7 @@ module Synapse
     end
 
     class DuplicationCleanupInterceptorTest < Test::Unit::TestCase
-      def test_intercept
+      should 'forget recorded commands only if a transient error occurs' do
         recorder = DuplicationRecorder.new
         interceptor = DuplicationCleanupInterceptor.new recorder
 

data/test/command/gateway/interval_retry_scheduler_test.rb

@@ -0,0 +1,42 @@
+require 'test_helper'
+require 'eventmachine'
+
+module Synapse
+  module Command
+    class IntervalRetrySchedulerTest < Test::Unit::TestCase
+
+      def setup
+        @maxRetries = 3
+
+        @scheduler = IntervalRetryScheduler.new 5.0, @maxRetries
+        @command = CommandMessage.as_message Object.new
+        @dispatcher = proc {}
+      end
+
+      should 'schedule up until the max number of retries' do
+        failures = []
+
+        mock(EventMachine).add_timer(5.0, &@dispatcher).times(@maxRetries)
+
+        @maxRetries.times do
+          failures.push RuntimeError.new
+          assert @scheduler.schedule @command, failures, @dispatcher
+        end
+
+        failures.push RuntimeError.new
+        refute @scheduler.schedule @command, failures, @dispatcher
+      end
+
+      should 'not schedule if failure was explicitly non-transient' do
+        failure = CommandValidationError.new
+        refute @scheduler.schedule @command, [failure], @dispatcher
+      end
+
+      should 'not schedule if cause of failure was explicitly non-transient' do
+        failure = CommandExecutionError.new NonTransientError.new
+        refute @scheduler.schedule @command, [failure], @dispatcher
+      end
+
+    end # IntervalRetrySchedulerTest
+  end # Command
+end

data/test/command/gateway/retrying_callback_test.rb

@@ -0,0 +1,57 @@
+require 'test_helper'
+
+module Synapse
+  module Command
+    class RetryingCallbackTest < Test::Unit::TestCase
+
+      def setup
+        @command = CommandMessage.as_message Object.new
+        @delegate = Object.new
+        @retry_scheduler = Object.new
+        @command_bus = Object.new
+
+        @callback = RetryingCallback.new @delegate, @command, @retry_scheduler, @command_bus
+      end
+
+      should 'notify delegate of a successful dispatch' do
+        result = Object.new
+
+        mock(@delegate).on_success(result)
+        @callback.on_success result
+      end
+
+      should 'not notify delegate of a failed dispatch when rescheduling' do
+        failures = [RuntimeError.new]
+
+        mock(@command_bus).dispatch_with_callback(@command, @callback)
+
+        mock(@retry_scheduler).schedule(@command, failures, is_a(Proc)) do |_, _, dispatcher|
+          dispatcher.call
+          true
+        end
+
+        @callback.on_failure failures.last
+      end
+
+      should 'notify delegate of a failed dispatch when not rescheduling' do
+        failures = [RuntimeError.new]
+
+        mock(@retry_scheduler).schedule(@command, failures, is_a(Proc)) do
+          false
+        end
+        mock(@delegate).on_failure(failures.last)
+
+        @callback.on_failure failures.last
+      end
+
+      should 'notify delegate of a failed dispatch on an unchecked exception' do
+        failure = ThreadError.new
+
+        mock(@delegate).on_failure(failure)
+
+        @callback.on_failure failure
+      end
+
+    end
+  end
+end

data/test/command/gateway_test.rb

@@ -4,20 +4,54 @@ module Synapse
   module Command
 
     class CommandGatewayTest < Test::Unit::TestCase
-      def test_send
-        command_bus = Object.new
-        gateway = CommandGateway.new command_bus
+      def setup
+        @command_bus = Object.new
+        @gateway = CommandGateway.new @command_bus
+      end
 
+      should 'wrap bare command objects in command messages before dispatch' do
         command = Object.new
         command_message = CommandMessage.build do |builder|
           builder.payload = command
         end
 
-        mock(command_bus).dispatch(is_a(CommandMessage)).ordered
-        mock(command_bus).dispatch(command_message).ordered
+        mock(@command_bus).dispatch_with_callback(is_a(CommandMessage), anything).ordered
+        mock(@command_bus).dispatch_with_callback(command_message, anything).ordered
+
+        @gateway.send command
+        @gateway.send command_message
+      end
+
+      should 'wrap callback in RetryingCallback if RetryScheduler' do
+        @gateway.retry_scheduler = IntervalRetryScheduler.new 3, 3
+
+        command = Object.new
+        callback = CommandCallback.new
+
+        mock(@command_bus).dispatch_with_callback(is_a(CommandMessage), is_a(RetryingCallback))
+
+        @gateway.send_with_callback command, callback
+      end
+
+      should 'send a command and wait for it to be dispatched' do
+        @gateway.retry_scheduler = IntervalRetryScheduler.new 3, 3
+
+        command = Object.new
+        result = Object.new
+
+        mock(@command_bus).dispatch_with_callback(is_a(CommandMessage), is_a(RetryingCallback)) do |message, callback|
+          callback.on_success result
+        end
+
+        received_result = nil
+
+        Thread.new do
+          received_result = @gateway.send_and_wait(command)
+        end
 
-        gateway.send command
-        gateway.send command_message
+        wait_until do
+          received_result.equal? result
+        end
       end
     end
 

data/test/command/interceptor_chain_test.rb

@@ -4,7 +4,7 @@ module Synapse
   module Command
 
     class InterceptorChainTest < Test::Unit::TestCase
-      def test_proceed
+      should 'allow interceptors to control the flow of dispatch' do
         unit = Object.new
         interceptor = Object.new
         interceptors = Array.new << interceptor

data/test/command/message_test.rb

@@ -0,0 +1,17 @@
+require 'test_helper'
+
+module Synapse
+  module Command
+    class CommandMessageTest < Test::Unit::TestCase
+      should 'not wrap objects that are already command messages' do
+        command = Object.new
+        command_message = CommandMessage.build
+
+        assert_same command_message, CommandMessage.as_message(command_message)
+
+        wrapped = CommandMessage.as_message(command)
+        assert_same command, wrapped.payload
+      end
+    end
+  end
+end

data/test/command/serialization_test.rb

@@ -4,7 +4,7 @@ module Synapse
   module Command
 
     class SerializationOptimizingInterceptorTest < Test::Unit::TestCase
-      def test_intercept
+      should 'register a serialization optimizing listener to the current unit of work' do
         interceptor = SerializationOptimizingInterceptor.new
 
         command = CommandMessage.build
@@ -19,7 +19,7 @@ module Synapse
     end
 
     class SerializationOptimizingListenerTest < Test::Unit::TestCase
-      def test_on_event_registered
+      should 'wrap event messages with serialization aware event messages' do
         listener = SerializationOptimizingListener.new
         unit = Object.new
 

data/test/command/simple_command_bus_test.rb

@@ -15,7 +15,7 @@ module Synapse
         end
       end
 
-      def test_dispatch
+      should 'dispatch a command message to its registered handler' do
         handler = Object.new
         command = CommandMessage.build do |m|
           m.payload = TestCommand.new
@@ -28,7 +28,7 @@ module Synapse
         @command_bus.dispatch command
       end
 
-      def test_dispatch_result
+      should 'invoke a callback with the return value from a command handler' do
         handler = Object.new
         callback = Object.new
         command = CommandMessage.build do |m|
@@ -47,7 +47,7 @@ module Synapse
         @command_bus.dispatch_with_callback command, callback
       end
 
-      def test_dispatch_no_handler
+      should 'raise an exception when a dispatched command has no registered handler' do
         command = CommandMessage.build do |m|
           m.payload = TestCommand.new
         end
@@ -58,7 +58,7 @@ module Synapse
         @command_bus.dispatch_with_callback command, callback
       end
 
-      def test_dispatch_rollback_on_exception
+      should 'roll back the current unit of work if the command handler raises an exception' do
         handler = Object.new
         command = CommandMessage.build do |m|
           m.payload = TestCommand.new
@@ -81,7 +81,7 @@ module Synapse
         @command_bus.dispatch_with_callback command, callback
       end
 
-      def test_dispatch_commit_on_exception
+      should 'commit the current unit of work if the command handler raises an exception' do
         handler = Object.new
         command = CommandMessage.build do |m|
           m.payload = TestCommand.new
@@ -108,7 +108,7 @@ module Synapse
         @command_bus.dispatch_with_callback command, callback
       end
 
-      def test_subscribe
+      should 'log when a subscribed handler is replaced' do
         handler = Object.new
 
         mock(@logger).debug(anything).ordered
@@ -118,7 +118,7 @@ module Synapse
         @command_bus.subscribe TestCommand, handler
       end
 
-      def test_unsubscribe
+      should 'log when a handler is unsubscribed' do
         handler_a = Object.new
         handler_b = Object.new
 

data/test/command/validation_test.rb

@@ -5,16 +5,16 @@ module Synapse
   module Command
 
     class ActiveModelValidationFilterTest < Test::Unit::TestCase
-      def test_filter
+      should 'continue if payload of a command message is valid' do
         message = CommandMessage.build do |m|
-          m.payload = CreatePersonCommand.new 'River'
+          m.payload = CreatePersonCommand.new 'River Tam'
         end
 
         filter = ActiveModelValidationFilter.new
         filter.filter message
       end
 
-      def test_filter_fails
+      should 'raise an exception if payload of a command message is invalid' do
         message = CommandMessage.build do |m|
           m.payload = CreatePersonCommand.new nil
         end