synapse-core 0.5.4 → 0.5.5

data/lib/synapse/command/async_command_bus.rb

@@ -1,5 +1,3 @@
-require 'thread/pool'
-
 module Synapse
   module Command
     # Command bus that uses a thread pool to asynchronously execute commands, invoking the given
@@ -7,8 +5,8 @@ module Synapse
     #
     # @todo Look into non-blocking circular buffers or LMAX Disruptor
     class AsynchronousCommandBus < SimpleCommandBus
-      # Pool of dispatching threads backed by a queue
-      # @return [Thread::Pool]
+      # Pool of worker threads that dispatch commands from a queue
+      # @return [Contender::Pool::ThreadPoolExecutor]
       attr_accessor :thread_pool
 
       # @api public
@@ -16,7 +14,7 @@ module Synapse
       # @param [CommandCallback] callback
       # @return [undefined]
       def dispatch_with_callback(command, callback)
-        @thread_pool.process do
+        @thread_pool.execute do
           super command, callback
         end
       end

data/lib/synapse/common.rb

@@ -3,7 +3,6 @@ require 'synapse/common/identifier'
 require 'synapse/common/message'
 require 'synapse/common/message_builder'
 
-require 'synapse/common/concurrency/executor'
 require 'synapse/common/concurrency/identifier_lock'
 require 'synapse/common/concurrency/public_lock'
 

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

@@ -3,13 +3,14 @@ module Synapse
     # Definition builder used to build an asynchronous command bus
     #
     # @see SimpleCommandBusDefinitionBuilder For additional options
+    # @see Contender::Pool::ThreadPoolExecutor For pool 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
+    #     use_pool_options size: 2
     #   end
     class AsynchronousCommandBusDefinitionBuilder < SimpleCommandBusDefinitionBuilder
       include ThreadPoolDefinitionBuilder
@@ -19,7 +20,7 @@ module Synapse
       # @return [undefined]
       def populate_defaults
         super
-        use_threads 4
+        use_pool_options size: 4
       end
 
       # @param [UnitOfWorkFactory] unit_factory

data/lib/synapse/configuration/component/{mixin → shared}/thread_pool.rb

@@ -1,25 +1,27 @@
 module Synapse
   module Configuration
     # Mixin for a definition builder that creates a service that is backed by a thread pool
+    # @see Contender::Pool::ThreadPoolExecutor For pool options
     module ThreadPoolDefinitionBuilder
       extend ActiveSupport::Concern
 
-      # Sets the upper and lower limits of the size of the thread pool
+      # Sets the options for the thread pool
       #
-      # @param [Integer] min_threads
-      # @param [Integer] max_threads
+      # @param [Hash] pool_options
       # @return [undefined]
-      def use_threads(min_threads, max_threads = nil)
-        @min_threads = min_threads
-        @max_threads = max_threads
+      def use_pool_options(pool_options)
+        @pool_options = pool_options
       end
 
     protected
 
       # Creates a thread pool with the configured options
-      # @return [Thread::Pool]
+      # @return [Contender::Pool::ThreadPoolExecutor]
       def create_thread_pool
-        Thread.pool @min_threads, @max_threads
+        pool = Contender::Pool::ThreadPoolExecutor.new @pool_options
+        pool.start
+
+        pool
       end
     end # ThreadPoolDefinitionBuilder
   end # Configuration

data/lib/synapse/configuration/dependent.rb

@@ -1,6 +1,6 @@
 module Synapse
   module Configuration
-    # Mixin for an object defines its dependencies so that they can be auto-injected by the 
+    # Mixin for an object defines its dependencies so that they can be auto-injected by the
     # service container after it has been instantiated
     #
     # Note that this only supports setter injection
@@ -20,7 +20,7 @@ module Synapse
         def depends_on(service, *args)
           options = args.extract_options!
 
-          attribute = options[:attribute] || service
+          attribute = options[:as] || service
           attr_accessor attribute
 
           self.dependencies[service] = attribute

data/lib/synapse/configuration/ext.rb

@@ -1,35 +1,64 @@
 module Synapse
-  # @return [Configuration::Container]
-  mattr_accessor :container
+  class << self
+    # @return [Configuration::Container]
+    attr_accessor :container
 
-  # @return [Configuration::ContainerBuilder]
-  mattr_accessor :container_builder
+    # @return [Configuration::ContainerBuilder]
+    attr_accessor :container_builder
 
-  # Initializes the service container and the container builder
-  #
-  # The given block is executed in the container of the container builder. Factory blocks are
-  # always deferred until the service is needed to build another service or is manually
-  # requested from the container.
-  #
-  # This method can be called multiple times without losing the state of the container.
-  #
-  # @example
-  #   Synapse.build do
-  #     definition :account_projection do
-  #       tag :event_listener, :projection
-  #       use_factory do
-  #         Bank::Projections::AccountProjection.new
-  #       end
-  #     end
-  #   end
-  #
-  # @see Configuration::ContainerBuilder#build_with
-  # @param [Proc] block
-  # @return [undefined]
-  def self.build(&block)
-    self.container ||= Configuration::Container.new
-    self.container_builder ||= Configuration::ContainerBuilder.new self.container
+    # Initializes the service container and the container builder
+    #
+    # The given block is executed in the container of the container builder. Factory blocks are
+    # always deferred until the service is needed to build another service or is manually
+    # requested from the container.
+    #
+    # This method can be called multiple times without losing the state of the container.
+    #
+    # @example
+    #   Synapse.build do
+    #     definition :account_projection do
+    #       tag :event_listener, :projection
+    #       use_factory do
+    #         Bank::Projections::AccountProjection.new
+    #       end
+    #     end
+    #   end
+    #
+    # @see Configuration::ContainerBuilder#build_with
+    # @param [Proc] block
+    # @return [undefined]
+    def build(&block)
+      self.container ||= Configuration::Container.new
+      self.container_builder ||= Configuration::ContainerBuilder.new self.container
 
-    self.container_builder.build_with(&block)
+      self.container_builder.build_with(&block)
+    end
+
+    # Initializes the service container and the container builder and applies simple defaults for
+    # getting started with a single node setup
+    #
+    # @example
+    #   Synapse.build_with_defaults do
+    #     # Setup things like command handlers, event listeners and repositories
+    #   end
+    #
+    # @see Configuration::ContainerBuilder#build_with
+    # @param [Proc] block
+    # @return [undefined]
+    def build_with_defaults(&block)
+      build do
+        converter_factory
+        serializer
+        upcaster_chain
+
+        unit_factory
+        simple_command_bus
+        gateway
+
+        simple_event_bus
+      end
+
+      build &block
+    end
   end
 end

data/lib/synapse/configuration.rb

@@ -5,7 +5,7 @@ require 'synapse/configuration/definition_builder'
 require 'synapse/configuration/dependent'
 require 'synapse/configuration/ext'
 
-require 'synapse/configuration/component/mixin/thread_pool'
+require 'synapse/configuration/component/shared/thread_pool'
 require 'synapse/configuration/component/command_bus'
 require 'synapse/configuration/component/event_bus'
 # Has to be loaded before event sourcing

data/lib/synapse/domain/aggregate_root.rb

@@ -1,6 +1,22 @@
 module Synapse
   module Domain
-    # Mixin module for a basic aggregate root
+    # Mixin module for a basic aggregate root that is not event-sourced
+    #
+    # The persistence mechanism is left up to the aggregate root that uses this mixin. Any sort of
+    # ORM can be used to persist aggregates.
+    #
+    # If optimistic locking is used, the ORM must increment the version field before saving.
+    #
+    #   class Order
+    #     include Synapse::Domain::AggregateRoot
+    #     include MongoMapper::Document
+    #
+    #     key :version, Integer
+    #
+    #     before_save { self.version += 1 }
+    #   end
+    #
+    # @see Repository::SimpleRepository
     module AggregateRoot
       # @return [Boolean] True if this aggregate has been marked for deletion
       attr_reader :deleted
@@ -14,6 +30,8 @@ module Synapse
       attr_reader :version
 
       # Marks this aggregate as committed by a repository
+      #
+      # @api public
       # @return [undefined]
       def mark_committed
         if @event_container
@@ -23,6 +41,8 @@ module Synapse
       end
 
       # Returns the number of uncommitted events published by this aggregate
+      #
+      # @api public
       # @return [Integer]
       def uncommitted_event_count
         unless @event_container
@@ -33,6 +53,8 @@ module Synapse
       end
 
       # Returns a domain event strema containing any uncommitted events published by this aggregate
+      #
+      # @api public
       # @return [DomainEventStream]
       def uncommitted_events
         unless @event_container
@@ -47,7 +69,8 @@ module Synapse
       # If an event registration listener is added after events have already been registered, it
       # will still get a change to process the uncommitted events in this aggregate.
       #
-      # @param [#call] listener
+      # @api public
+      # @param [Proc] listener
       # @return [undefined]
       def add_registration_listener(&listener)
         event_container.add_registration_listener listener
@@ -57,10 +80,13 @@ module Synapse
 
       # Publishes a domain event with the given payload and optional metadata
       #
+      # Before any events are published, the aggregate identifier must be set.
+      #
       # @api public
+      # @raise [AggregateIdentifierNotInitializedError] If identifier not set
       # @param [Object] payload Payload of the message; the actual event object
       # @param [Hash] metadata Metadata associated with the event
-      # @return [DomainEventMessage] The event that will be committed
+      # @return [DomainEventMessage] The event that will be published
       def publish_event(payload, metadata = nil)
         event_container.register_event payload, metadata
       end
@@ -73,18 +99,9 @@ module Synapse
         @deleted = true
       end
 
-      # Initializes the event container with the given sequence number
-      #
-      # @param [Integer] last_sequence_number
-      #   The sequence number of the last committed event for this aggregate
-      #
-      # @return [undefined]
-      def initialize_event_container(last_sequence_number)
-        event_container.initialize_sequence_number last_sequence_number
-        @last_sequence_number = last_sequence_number >= 0 ? last_sequence_number : nil
-      end
-
       # Returns the sequence number of the last committed event
+      #
+      # @api public
       # @return [Integer]
       def last_committed_sequence_number
         unless @event_container
@@ -96,6 +113,16 @@ module Synapse
 
     private
 
+      # Initializes the event container with the given sequence number
+      #
+      # @param [Integer] last_sequence_number
+      #   The sequence number of the last committed event for this aggregate
+      # @return [undefined]
+      def initialize_event_container(last_sequence_number)
+        event_container.initialize_sequence_number last_sequence_number
+        @last_sequence_number = last_sequence_number >= 0 ? last_sequence_number : nil
+      end
+
       # Initializes the uncommitted event container for this aggregate, if not already
       #
       # @raise [AggregateIdentifierNotInitializedError] If identifier not set
@@ -112,9 +139,6 @@ module Synapse
 
         @event_container
       end
-    end
-
-    # Raised when an event is published but the aggregate identifier is not set
-    class AggregateIdentifierNotInitializedError < NonTransientError; end
-  end
+    end # AggregateRoot
+  end # Domain
 end

data/lib/synapse/domain/errors.rb

@@ -0,0 +1,9 @@
+module Synapse
+  module Domain
+    # Raised when an event is published but the aggregate identifier is not set
+    class AggregateIdentifierNotInitializedError < NonTransientError; end
+
+    # Raised when the end of a domain event stream has been reached
+    class EndOfStreamError < NonTransientError; end
+  end
+end

data/lib/synapse/domain/event_container.rb

@@ -56,7 +56,7 @@ module Synapse
       # If the listener is added after events have already registered with the container, it will
       # be called with a backlog of events to process.
       #
-      # @param [#call] listener
+      # @param [Proc] listener
       # @return [undefined]
       def add_registration_listener(listener)
         @listeners.push listener
@@ -122,6 +122,6 @@ module Synapse
       def next_sequence_number
         last_sequence_number ? last_sequence_number.next : 0
       end
-    end
-  end
+    end # EventContainer
+  end # Domain
 end

data/lib/synapse/domain/message.rb

@@ -53,6 +53,6 @@ module Synapse
         builder.aggregate_id = @aggregate_id
         builder.sequence_number = @sequence_number
       end
-    end
-  end
+    end # DomainEventMessage
+  end # Domain
 end

data/lib/synapse/domain/message_builder.rb

@@ -20,6 +20,6 @@ module Synapse
       def build
         DomainEventMessage.new @id, @metadata, @payload, @timestamp, @aggregate_id, @sequence_number
       end
-    end
-  end
+    end # DomainEventMessageBuilder
+  end # Domain
 end

data/lib/synapse/domain/simple_stream.rb

@@ -0,0 +1,39 @@
+module Synapse
+  module Domain
+    # Implementation of a domain event stream that holds a stream of events in memory
+    class SimpleDomainEventStream < DomainEventStream
+      def initialize(*events)
+        @events = events.flatten
+        @next_index = 0
+      end
+
+      # Returns true if the end of the stream has been reached
+      # @return [Boolean]
+      def end?
+        @next_index >= @events.size
+      end
+
+      # Returns the next event in the stream and moves the stream's pointer forward
+      #
+      # @raise [EndOfStreamError] If the end of the stream has been reached
+      # @return [DomainEventMessage]
+      def next_event
+        assert_valid
+
+        event = @events.at @next_index
+        @next_index += 1
+
+        event
+      end
+
+      # Returns the next event in the stream without moving the stream's pointer forward
+      #
+      # @raise [EndOfStreamError] If the end of the stream has been reached
+      # @return [DomainEventMessage]
+      def peek
+        assert_valid
+        @events.at @next_index
+      end
+    end # SimpleDomainEventStream
+  end # Domain
+end

data/lib/synapse/domain/stream.rb

@@ -64,45 +64,6 @@ module Synapse
           raise EndOfStreamError
         end
       end
-    end
-
-    # Raised when the end of a domain event stream has been reached
-    class EndOfStreamError < NonTransientError; end
-
-    # Implementation of a domain event stream that holds a stream of events in memory
-    class SimpleDomainEventStream < DomainEventStream
-      def initialize(*events)
-        @events = events.flatten
-        @next_index = 0
-      end
-
-      # Returns true if the end of the stream has been reached
-      # @return [Boolean]
-      def end?
-        @next_index >= @events.size
-      end
-
-      # Returns the next event in the stream and moves the stream's pointer forward
-      #
-      # @raise [EndOfStreamError] If the end of the stream has been reached
-      # @return [DomainEventMessage]
-      def next_event
-        assert_valid
-
-        event = @events.at @next_index
-        @next_index += 1
-
-        event
-      end
-
-      # Returns the next event in the stream without moving the stream's pointer forward
-      #
-      # @raise [EndOfStreamError] If the end of the stream has been reached
-      # @return [DomainEventMessage]
-      def peek
-        assert_valid
-        @events.at @next_index
-      end
-    end
-  end
+    end # DomainEventStream
+  end # Domain
 end

data/lib/synapse/domain.rb

@@ -1,5 +1,8 @@
+require 'synapse/domain/errors'
+
 require 'synapse/domain/aggregate_root'
 require 'synapse/domain/event_container'
 require 'synapse/domain/message'
 require 'synapse/domain/message_builder'
 require 'synapse/domain/stream'
+require 'synapse/domain/simple_stream'

data/lib/synapse/event_sourcing/aggregate_root.rb

@@ -1,6 +1,106 @@
 module Synapse
   module EventSourcing
     # Mixin for the root entity of an aggregate that is initialized from a historical event stream
+    #
+    # = Handling events
+    #
+    # For ease of use, the event mapping DSL is included in event-sourced aggregates. This includes
+    # both the aggregate root and any entities that are a member of the aggregate.
+    #
+    # This mapping DSL can be used to map handlers for events that have been applied to the
+    # aggregate
+    #
+    #   class Order
+    #     include Synapse::EventSourcing::AggregateRoot
+    #
+    #     def add_item(sku, quantity, unit_price)
+    #       # Do business logic validation here
+    #       apply(new ItemsAddedToOrder(id, sku, quantity, unit_price))
+    #     end
+    #
+    #     map_event ItemsAddedToOrder do |event|
+    #       @value = @value + (event.quantity * event.unit_price)
+    #       @line_items.add(OrderLineItem.new(sku, quantity, unit_price))
+    #     end
+    #   end
+    #
+    # Events applied to the aggregate root are cascaded down to any child entities of the aggregate
+    # root. Events applied to a child entity are actually applied to the aggregate root's event
+    # container, and are then cascaded down to the child entities.
+    #
+    # = Initialization
+    #
+    # An aggregate can be initialized in three ways:
+    #
+    # - Created by the caller using new, usually to create a new aggregate
+    # - Allocated, then initialized from an event stream
+    # - Deserialized from a snapshot
+    #
+    # Because of the different ways the aggregate can be created, it is necessary to separate out
+    # the logic needed to create data structures required by the aggregate to function.
+    #
+    # Ruby does not support method overloading, so there is a hook provided to do any logic
+    # necessary to instantiate the aggregate, such as creating collections.
+    #
+    #   class Order
+    #     include Synapse::EventSourcing::AggregateRoot
+    #
+    #     def initialize(id, max_value)
+    #       pre_initialize
+    #       apply(OrderCreated.new(id, max_value))
+    #     end
+    #
+    #   protected
+    #
+    #     def pre_initialize
+    #       @line_items = Set.new
+    #     end
+    #   end
+    #
+    # Instead of using the pre-initialization hook, you can also do lazy initialization.
+    #
+    #   class Order
+    #     include Synapse::EventSourcing::AggregateRoot
+    #
+    #     def line_items
+    #       @line_items ||= Set.new
+    #     end
+    #   end
+    #
+    # = Snapshots
+    #
+    # When the event stream for an aggregate becomes large, it can put a drain on the application
+    # to have to load the entire stream of an aggregate just to perform a single operation upon
+    # it.
+    #
+    # To solve this issue, Synapse supports snapshotting aggregates. The built-in way to snapshot
+    # is simply to serialize the aggregate root, since it contains entire state of the aggregate.
+    #
+    # When using a marshalling serializer, like the built-in Ruby marshaller or ones like Oj and
+    # Ox, no work needs to be done to prepare the aggregate for serialization. However, when using
+    # the attribute serializer, you have to treat snapshots as mementos.
+    #
+    #   class Order
+    #     include Synapse::EventSourcing::AggregateRoot
+    #
+    #     def attributes
+    #       line_items = @line_items.map { |li| li.attributes }
+    #       { id: @id, value: @value }
+    #     end
+    #
+    #     # Note that this is called after #allocate
+    #     def attributes=(attributes)
+    #       @id = attributes[:id]
+    #       @value = attributes[:value]
+    #       # Yeah, it's pretty ugly to support this
+    #       @line_items = attributes[:line_items].map do |line_item|
+    #         OrderLineItem.allocate.tap { |li| li.attributes = line_item }
+    #       end
+    #     end
+    #   end
+    #
+    # It would be nice to have something like XStream to make serialization easier, but as far as
+    # I can tell, there's nothing even close to it for Ruby.
     module AggregateRoot
       extend ActiveSupport::Concern
       include Domain::AggregateRoot
@@ -119,6 +219,6 @@ module Synapse
           entity.handle_aggregate_event event
         end
       end
-    end
-  end
+    end # AggregateRoot
+  end # EventSourcing
 end

data/lib/synapse/event_sourcing/caching.rb

@@ -28,7 +28,7 @@ module Synapse
         if aggregate.nil?
           aggregate = super aggregate_id, expected_version
         elsif aggregate.deleted?
-          raise AggregateDeletedError
+          raise AggregateDeletedError.new type_identifier, aggregate_id
         end
 
         register_listener CacheClearingUnitOfWorkListener.new aggregate_id, @cache

data/lib/synapse/event_sourcing/entity.rb

@@ -59,6 +59,6 @@ module Synapse
 
         @aggregate_root.handle_member_event payload, metadata
       end
-    end
-  end
+    end # Entity
+  end # EventSourcing
 end

data/lib/synapse/event_sourcing/member.rb

@@ -2,17 +2,16 @@ module Synapse
   module EventSourcing
     # Base mixin for a member of an aggregate which has its state mutated by events that are
     # applied to the aggregate
+    #
+    # @see AggregateRoot
+    # @see Entity
     module Member
       extend ActiveSupport::Concern
 
       included do
-        # @return [Mapper::Mapping]
-        class_attribute :command_mapper
-
         # @return [Mapper::Mapping]
         class_attribute :event_mapper
 
-        self.command_mapper = Mapping::Mapper.new false
         self.event_mapper = Mapping::Mapper.new true
       end
 
@@ -33,15 +32,6 @@ module Synapse
           @child_entities ||= Set.new
         end
 
-        # @see Mapper#map
-        # @param [Class] type
-        # @param [Object...] args
-        # @param [Proc] block
-        # @return [undefined]
-        def map_command(type, *args, &block)
-          commnad_mapper.map type, *args, &block
-        end
-
         # @see Mapper#map
         # @param [Class] type
         # @param [Object...] args