synapse-core 0.4.0 → 0.5.1

data/lib/synapse/configuration/component/upcasting/upcaster_chain.rb

@@ -0,0 +1,61 @@
+module Synapse
+  module Configuration
+    # Definition builder used to create an upcaster chain
+    #
+    # Note that order is very important when building an upcaster chain; the container maintains
+    # order when upcasters are registered as service definitions.
+    #
+    # @example The minimum possible effort to build an upcaster chain
+    #   upcaster_chain
+    #
+    # @example Create an upcaster chain using a different identifier and properties
+    #   upcaster_chain :alt_upcaster_chain do
+    #     use_converter_factory :alt_converter_factory
+    #     use_upcaster_tag :alt_upcaster
+    #   end
+    #
+    # @example Register an upcaster that will be picked up by an upcaster chain
+    #   factory :administrative_details_upcaster, :tag => :upcaster do
+    #     AdministrativeDetailsUpcaster.new
+    #   end
+    class UpcasterChainDefinitionBuilder < DefinitionBuilder
+      # Changes the converter factory
+      #
+      # @param [Symbol] converter_factory
+      # @return [undefined]
+      def use_converter_factory(converter_factory)
+        @converter_factory = converter_factory
+      end
+
+      # Changes the tag to use to automatically register upcasters
+      #
+      # @param [Symbol] upcaster_tag
+      # @return [undefined]
+      def use_upcaster_tag(upcaster_tag)
+        @upcaster_tag = upcaster_tag
+      end
+
+    protected
+
+      # @return [undefined]
+      def populate_defaults
+        identified_by :upcaster_chain
+
+        use_converter_factory :converter_factory
+        use_upcaster_tag :upcaster
+
+        use_factory do
+          converter_factory = resolve @converter_factory
+
+          upcaster_chain = Upcasting::UpcasterChain.new converter_factory
+          
+          with_tagged @upcaster_tag do |upcaster|
+            upcaster_chain.push upcaster
+          end
+
+          upcaster_chain
+        end
+      end
+    end # UpcasterChainDefinitionBuilder
+  end # Configuration
+end

data/lib/synapse/configuration/component/upcasting.rb

@@ -0,0 +1,15 @@
+module Synapse
+  module Configuration
+    class ContainerBuilder
+      # Creates and configures an upcaster chain
+      #
+      # @see UpcasterChainDefinitionBuilder
+      # @param [Symbol] identifier
+      # @param [Proc] block
+      # @return [undefined]
+      def upcaster_chain(identifier = nil, &block)
+        with_definition_builder UpcasterChainDefinitionBuilder, identifier, &block
+      end
+    end # ContainerBuilder
+  end # Configuration
+end

data/lib/synapse/configuration/container.rb

@@ -0,0 +1,80 @@
+module Synapse
+  module Configuration
+    # Container used for storing and resolving definitions of services
+    # @see ContainerBuilder
+    class Container
+      def initialize
+        @definitions = Hash.new
+        @logger = Logging.logger[self.class]
+      end
+
+      # Injects any configured dependencies into the given object
+      #
+      # @param [Dependent] object
+      # @return [undefined]
+      def inject_into(object)
+        return unless object.is_a? Dependent
+
+        dependencies = object.class.dependencies
+        dependencies.each_pair do |id, attribute|
+          resolved = resolve id
+          object.public_send "#{attribute}=", resolved
+        end
+      end
+
+      # Locates the definition for a service with the given identifier and resolves it to the
+      # object being provided
+      #
+      # @raise [ArgumentError] If definition could not be found and is required
+      # @param [Symbol] id
+      # @param [Boolean] optional Default is false
+      # @return [Object]
+      def resolve(id, optional = false)
+        if @definitions.has_key? id
+          @definitions[id].resolve
+        elsif not optional
+          raise ConfigurationError, 'Definition for service [%s] not found' % id
+        end
+      end
+
+      alias [] resolve
+
+      # Resolves any definitions that have the given tag
+      #
+      # @param [Symbol] tag
+      # @return [Array]
+      def resolve_tagged(tag)
+        resolved = Array.new
+
+        @definitions.each_value do |definition|
+          if definition.tags and definition.tags.include? tag
+            resolved.push definition.resolve
+          end
+        end
+
+        resolved
+      end
+
+      # Registers a service definition with this container
+      #
+      # @param [Symbol] id
+      # @param [Definition] definition
+      # @return [undefined]
+      def register(id, definition)
+        if @definitions.has_key? id
+          @logger.info 'Definition [%s] is being replaced' % id
+        end
+
+        @definitions.store id, definition
+      end
+
+      # Returns true if a service definition with the given identifier is registered
+      #
+      # @param [Symbol] id
+      # @return [Boolean]
+      def registered?(id)
+        @definitions.has_key? id
+      end
+    end
+  end
+end

data/lib/synapse/configuration/container_builder.rb

@@ -0,0 +1,108 @@
+module Synapse
+  module Configuration
+    # Provides a DSL for end-users to easily configure the Synapse service container
+    # @see Synapse#build
+    class ContainerBuilder
+      # Registered initializers that will be executed upon instantiation
+      # @return [Array]
+      class_attribute :initializers
+
+      # Registers a block that will be executed upon instantiation of a container builder
+      #
+      # This is useful for defining common services that are likely to be depended upon by
+      # other services being built
+      #
+      # @param [Proc] initializer
+      # @return [undefined]
+      def self.initializer(&initializer)
+        self.initializers ||= Array.new
+        self.initializers.push initializer
+      end
+
+      # @return [Container]
+      attr_reader :container
+
+      # @param [Container] container
+      # @return [undefined]
+      def initialize(container)
+        @container = container
+
+        if initializers
+          initializers.each do |initializer|
+            build_with(&initializer)
+          end
+        end
+      end
+
+      # Executes the given block in the context of the container builder
+      #
+      # @param [Proc] block
+      # @return [undefined]
+      def build_with(&block)
+        instance_exec(&block)
+      end
+
+      # Executes the given block in the context of a new definition builder
+      #
+      # @example
+      #   definition :account_projection do
+      #     tag :event_listener, :projection
+      #     use_factory do
+      #       AccountProjection.new
+      #     end
+      #   end
+      #
+      # @see #factory If the definition being created is simple
+      # @see DefinitionBuilder
+      # @param [Symbol] id
+      # @param [Proc] block
+      # @return [undefined]
+      def definition(id = nil, &block)
+        with_definition_builder DefinitionBuilder, id, &block
+      end
+
+      # Simple usage of the definition builder
+      #
+      # The given block is used as a deferred factory and will be executed in the context of the
+      # definition builder. If a tag option is provided, the definition will be tagged with the
+      # given symbols.
+      #
+      # The definition that is created will be a singleton.
+      #
+      # @example
+      #   factory :account_projection, :tag => [:event_listener, :projection] do
+      #     AccountProjection.new
+      #   end
+      #
+      # @see DefinitionBuilder#use_factory
+      # @param [Symbol] id
+      # @param [Object...] args
+      # @param [Proc] block
+      # @return [undefined]
+      def factory(id, *args, &block)
+        options = args.extract_options!
+
+        with_definition_builder DefinitionBuilder, id do
+          use_factory(&block)
+          if options.has_key? :tag
+            tag(*options.fetch(:tag))
+          end
+        end
+      end
+
+    protected
+
+      # Creates a definition builder of the given type, uses the identifier (if any is given),
+      # executes the block in the context of the definition builder, then finally builds and
+      # registers the definition with this builder's associate container.
+      #
+      # @param [Class] builder_type
+      # @param [Symbol] id
+      # @param [Proc] block
+      # @return [undefined]
+      def with_definition_builder(builder_type, id, &block)
+        builder_type.build @container, id, &block
+      end
+    end
+  end
+end

data/lib/synapse/configuration/definition.rb

@@ -0,0 +1,31 @@
+module Synapse
+  module Configuration
+    # Represents a definition for a service being provided by the container
+    # @see DefinitionBuilder
+    class Definition
+      # @return [Set] Symbols that this definition is tagged with
+      attr_reader :tags
+
+      # @param [Set] tags
+      # @param [Boolean] prototype
+      # @param [Proc] factory
+      # @param [Object] instance
+      # @return [undefined]
+      def initialize(tags, prototype, factory, instance)
+        @tags = tags
+        @prototype = prototype
+        @factory = factory
+        @instance = instance
+      end
+
+      # @return [Object]
+      def resolve
+        if @prototype
+          @factory.call
+        else
+          @instance ||= @factory.call
+        end
+      end
+    end # Definition
+  end # Configuration
+end

data/lib/synapse/configuration/definition_builder.rb

@@ -0,0 +1,138 @@
+module Synapse
+  module Configuration
+    # DSL for building service definitions
+    class DefinitionBuilder
+      # @return [Symbol]
+      attr_reader :id
+
+      # @yield [DefinitionBuilder]
+      # @param [Container] container
+      # @param [Symbol] id
+      # @param [Proc] block
+      # @return [undefined]
+      def self.build(container, id = nil, &block)
+        builder = self.new container, id
+        builder.instance_exec(&block) if block
+        builder.register_definition
+
+        builder.id
+      end
+
+      # @param [Container] container
+      # @param [Symbol] id
+      # @return [undefined]
+      def initialize(container, id = nil)
+        @container = container
+        @prototype = false
+        @tags = Set.new
+
+        populate_defaults
+
+        @id = id.to_sym if id
+      end
+
+      # @param [Symbol] id
+      # @return [undefined]
+      def identified_by(id)
+        @id = id.to_sym
+      end
+
+      # @return [undefined]
+      def anonymous
+        identified_by SecureRandom.hex 8
+      end
+
+      # @param [Symbol...] tags
+      # @return [undefined]
+      def tag(*tags)
+        @tags.merge tags.flatten
+      end
+
+      # @return [undefined]
+      def as_prototype
+        @prototype = true
+      end
+
+      # @return [undefined]
+      def as_singleton
+        @prototype = false
+      end
+
+      # @param [Proc] factory
+      # @return [undefined]
+      def use_factory(&factory)
+        @factory = proc do
+          instance_exec(&factory)
+        end
+      end
+
+      # @param [Object] instance
+      # @return [undefined]
+      def use_instance(instance)
+        @instance = instance
+      end
+
+      # If the given value is a symbol, it will be resolved using the container. Otherwise, it
+      # will be passed through
+      #
+      # @param [Object] value
+      # @return [Object]
+      def resolve(value, optional = false)
+        if value.is_a? Symbol
+          @container.resolve value, optional
+        else
+          value
+        end
+      end
+
+      # Resolves all services that have the given tag
+      #
+      # @param [Symbol] tag
+      # @return [Array]
+      def resolve_tagged(tag)
+        @container.resolve_tagged tag
+      end
+
+      # Convenience method for building composite services
+      #
+      # The given block will be executed in the context of the definition builder
+      #
+      # @param [Class] builder_type Defaults to DefinitionBuilder
+      # @param [Proc] block
+      # @return [Symbol] The identifier of the newly created service
+      def build_composite(builder_type = DefinitionBuilder, &block)
+        builder_type.build @container, &block
+      end
+
+      # @return [Definition]
+      def build_definition
+        Definition.new @tags, @prototype, @factory, @instance
+      end
+
+      # @return [undefined]
+      def register_definition
+        unless @id
+          raise ConfigurationError, 'No identifier set for the definition'
+        end
+
+        @container.register @id, build_definition
+      end
+
+    protected
+
+      # Sets the default values for the definition being built
+      # @return [undefined]
+      def populate_defaults; end
+
+      # Resolves any services with the given tag and yields them
+      #
+      # @yield [Object]
+      # @param [Symbol] tag
+      # @return [undefined]
+      def with_tagged(tag, &block)
+        tagged = resolve_tagged tag
+        tagged.each &block
+      end
+    end # DefinitionBuilder
+  end # Configuration
+end

data/lib/synapse/configuration/dependent.rb

@@ -0,0 +1,31 @@
+module Synapse
+  module Configuration
+    # 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
+    module Dependent
+      extend ActiveSupport::Concern
+
+      included do
+        # @return [Hash]
+        class_attribute :dependencies, instance_accessor: false
+        self.dependencies = Hash.new
+      end
+
+      module ClassMethods
+        # @param [Symbol] service
+        # @param [Object...] args
+        # @return [undefined]
+        def depends_on(service, *args)
+          options = args.extract_options!
+
+          attribute = options[:attribute] || service
+          attr_accessor attribute
+
+          self.dependencies[service] = attribute
+        end
+      end
+    end # Dependent
+  end # Configuration
+end

data/lib/synapse/configuration/ext.rb

@@ -0,0 +1,35 @@
+module Synapse
+  # @return [Configuration::Container]
+  mattr_accessor :container
+
+  # @return [Configuration::ContainerBuilder]
+  mattr_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
+
+    self.container_builder.build_with(&block)
+  end
+end

data/lib/synapse/configuration.rb

@@ -0,0 +1,32 @@
+require 'synapse/configuration/container'
+require 'synapse/configuration/container_builder'
+require 'synapse/configuration/definition'
+require 'synapse/configuration/definition_builder'
+require 'synapse/configuration/dependent'
+require 'synapse/configuration/ext'
+
+require 'synapse/configuration/component/command_bus'
+# Has to be loaded before asynchronous command bus definition builder
+require 'synapse/configuration/component/command_bus/simple_command_bus'
+require 'synapse/configuration/component/command_bus/async_command_bus'
+
+require 'synapse/configuration/component/event_bus'
+require 'synapse/configuration/component/event_bus/simple_event_bus'
+
+require 'synapse/configuration/component/repository'
+# Has to be loaded before event sourcing or simple repository definition builders
+require 'synapse/configuration/component/repository/locking_repository'
+require 'synapse/configuration/component/repository/simple_repository'
+
+require 'synapse/configuration/component/event_sourcing'
+require 'synapse/configuration/component/event_sourcing/repository'
+
+require 'synapse/configuration/component/serialization'
+require 'synapse/configuration/component/serialization/converter_factory'
+require 'synapse/configuration/component/serialization/serializer'
+
+require 'synapse/configuration/component/uow'
+require 'synapse/configuration/component/uow/unit_factory'
+
+require 'synapse/configuration/component/upcasting'
+require 'synapse/configuration/component/upcasting/upcaster_chain'

data/lib/synapse/domain/aggregate_root.rb

@@ -13,17 +13,6 @@ module Synapse
       # @return [Integer] The version of this aggregate
       attr_reader :version
 
-      # Adds a listener that will be notified when this aggregate registers an event to be published
-      #
-      # 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
-      # @return [undefined]
-      def add_registration_listener(&listener)
-        event_container.add_registration_listener listener
-      end
-
       # Marks this aggregate as committed by a repository
       # @return [undefined]
       def mark_committed
@@ -53,21 +42,37 @@ module Synapse
         @event_container.to_stream
       end
 
-    protected
-
-      # Publishes a domain event with the given payload and metadata (optional)
+      # Adds a listener that will be notified when this aggregate registers an event to be published
       #
-      # @param [Object] payload
-      #   Payload of the message; the actual event object
+      # 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 [Hash] metadata
-      #   Metadata associated with the event
+      # @param [#call] listener
+      # @return [undefined]
+      def add_registration_listener(&listener)
+        event_container.add_registration_listener listener
+      end
+
+    protected
+
+      # Publishes a domain event with the given payload and optional metadata
       #
+      # @api public
+      # @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
       def publish_event(payload, metadata = nil)
         event_container.register_event payload, metadata
       end
 
+      # Marks this aggregate for deletion by its repository
+      #
+      # @api public
+      # @return [undefined]
+      def mark_deleted
+        @deleted = true
+      end
+
       # Initializes the event container with the given sequence number
       #
       # @param [Integer] last_sequence_number
@@ -89,12 +94,6 @@ module Synapse
         @event_container.last_committed_sequence_number
       end
 
-      # Marks this aggregate for deletion by its repository
-      # @return [undefined]
-      def mark_deleted
-        @deleted = true
-      end
-
     private
 
       # Initializes the uncommitted event container for this aggregate, if not already
@@ -103,11 +102,11 @@ module Synapse
       # @return [EventContainer]
       def event_container
         unless @event_container
-          unless @id
+          unless id
             raise AggregateIdentifierNotInitializedError
           end
 
-          @event_container = EventContainer.new @id
+          @event_container = EventContainer.new id
           @event_container.initialize_sequence_number @last_sequence_number
         end
 

data/lib/synapse/domain/event_container.rb

@@ -34,11 +34,11 @@ module Synapse
       #
       # @return [DomainEventMessage] The event that will be committed
       def register_event(payload, metadata)
-        event = DomainEventMessage.build do |b|
-          b.aggregate_id = @aggregate_id
-          b.sequence_number = next_sequence_number
-          b.metadata = metadata
-          b.payload = payload
+        event = DomainEventMessage.build do |builder|
+          builder.aggregate_id = @aggregate_id
+          builder.sequence_number = next_sequence_number
+          builder.metadata = metadata
+          builder.payload = payload
         end
 
         @listeners.each do |listener|

data/lib/synapse/domain/message.rb

@@ -23,6 +23,22 @@ module Synapse
         EventMessageBuilder
       end
 
+      # Creates an event message using the given event object
+      #
+      # If the given object is an event message, it will be returned unchanged.
+      #
+      # @param [Object] event
+      # @return [EventMessage]
+      def self.as_message(event)
+        unless event.is_a? EventMessage
+          event = self.build do |builder|
+            builder.payload = event
+          end
+        end
+
+        event
+      end
+
     protected
 
       # @param [EventMessageBuilder] builder

data/lib/synapse/event_bus/event_listener.rb

@@ -3,6 +3,8 @@ module Synapse
     # Represents a listener that can be notified of events from an event bus. Implementations are
     # highly discouraged from throwing exceptions.
     #
+    # Consider using the event listener mixin that uses message wiring.
+    #
     # @abstract
     module EventListener
       # Called when an event is published to the event bus