synapse-core 0.1.2

data/lib/synapse/event_bus/event_listener.rb

@@ -0,0 +1,16 @@
+module Synapse
+  module EventBus
+    # Represents a listener that can be notified of events from an event bus. Implementations are
+    # highly discouraged from throwing exceptions.
+    #
+    # @abstract
+    module EventListener
+      # Called when an event is published to the event bus
+      #
+      # @abstract
+      # @param [EventMessage] event
+      # @return [undefined]
+      def notify(event); end
+    end
+  end
+end

data/lib/synapse/event_bus/event_listener_proxy.rb

@@ -0,0 +1,12 @@
+module Synapse
+  module EventBus
+    # @abstract
+    module EventListenerProxy
+      extend EventListener
+
+      # @abstract
+      # @return [Class]
+      def target_type; end
+    end
+  end
+end

data/lib/synapse/event_bus/simple_event_bus.rb

@@ -0,0 +1,69 @@
+module Synapse
+  module EventBus
+    # Implementation of an event bus that notifies any subscribed event listeners in the calling
+    # thread. Listeners are expected to implement asynchronous handing themselves, if desired.
+    class SimpleEventBus < EventBus
+      def initialize
+        @listeners = Set.new
+        @logger = Logging.logger.new self.class
+      end
+
+      # @param [EventMessage...] events
+      # @return [undefined]
+      def publish(*events)
+        if @listeners.empty?
+          return
+        end
+
+        events.flatten!
+        events.each do |event|
+          @listeners.each do |listener|
+            if @logger.debug?
+              listener_type = actual_type listener
+              @logger.debug 'Dispatching event [%s] to listener [%s]' %
+                [event.payload_type, listener_type]
+            end
+
+            listener.notify event
+          end
+        end
+      end
+
+      # @param [EventListener] listener
+      # @return [undefined]
+      def subscribe(listener)
+        listener_type = actual_type listener
+
+        if @listeners.add? listener
+          @logger.debug 'Event listener [%s] subscribed' % listener_type
+        else
+          @logger.info 'Event listener [%s] not added, was already subscribed' % listener_type
+        end
+      end
+
+      # @param [EventListener] listener
+      # @return [undefined]
+      def unsubscribe(listener)
+        listener_type = actual_type listener
+
+        if @listeners.delete? listener
+          @logger.debug 'Event listener [%s] unsubscribed' % listener_type
+        else
+          @logger.info 'Event listener [%s] not removed, was not subscribed' % listener_type
+        end
+      end
+
+    private
+
+      # @param [EventListener] listener
+      # @return [Class]
+      def actual_type(listener)
+        if listener.respond_to? :proxied_type
+          listener.proxied_type
+        else
+          listener.class
+        end
+      end
+    end
+  end
+end

data/lib/synapse/event_bus/wiring.rb

@@ -0,0 +1,23 @@
+module Synapse
+  module EventBus
+    # Mixin for an event listener that wishes to use the wiring DSL
+    module WiringEventListener
+      extend ActiveSupport::Concern
+      include EventListener
+      include Wiring::MessageWiring
+
+      included do
+        self.wire_registry = Wiring::WireRegistry.new true
+      end
+
+      # @param [EventMessage] event
+      # @return [undefined]
+      def notify(event)
+        wire = self.wire_registry.wire_for event.payload_type
+        if wire
+          invoke_wire event, wire
+        end
+      end
+    end
+  end
+end

data/lib/synapse/event_sourcing/aggregate_factory.rb

@@ -0,0 +1,69 @@
+module Synapse
+  module EventSourcing
+    # Represents a mechanism for creating aggregates to be initialized by an event stream
+    # @abstract
+    class AggregateFactory
+      # Instantiates an aggregate using the given aggregate identifier and first event
+      #
+      # The first event is either the event used to create the aggregate or the most recent
+      # snapshot event for the aggregate.
+      #
+      # @abstract
+      # @param [Object] aggregate_id
+      # @param [DomainEventMessage] first_event
+      # @return [AggregateRoot]
+      def create_aggregate(aggregate_id, first_event); end
+
+      # @abstract
+      # @return [Class] Type of aggregate being created by this factory
+      def aggregate_type; end
+
+      # @abstract
+      # @return [String] Type identifier used to store the aggregate in the event store
+      def type_identifier; end
+    end
+
+    # Aggregate factory that uses a convention to create instances of aggregates
+    class GenericAggregateFactory < AggregateFactory
+      # @return [Class]
+      attr_reader :aggregate_type
+
+      # @return [String]
+      attr_reader :type_identifier
+
+      # @param [Class] aggregate_type
+      # @return [undefined]
+      def initialize(aggregate_type)
+        @aggregate_type = aggregate_type
+        @type_identifier = aggregate_type.to_s.demodulize
+      end
+
+      # @param [Object] aggregate_id
+      # @param [DomainEventMessage] first_event
+      # @return [AggregateRoot]
+      def create_aggregate(aggregate_id, first_event)
+        payload = first_event.payload
+
+        if payload.is_a? AggregateRoot
+          aggregate = payload
+        else
+          aggregate = @aggregate_type.allocate
+        end
+
+        post_process aggregate
+      end
+
+    protected
+
+      # Performs any processing that must be done on an aggregate instance that was reconstructed
+      # from a snapshot event. Implementations may choose to modify the existing instance or return
+      # a new instance.
+      #
+      # @param [AggregateRoot] aggregate
+      # @return [AggregateRoot]
+      def post_process(aggregate)
+        aggregate
+      end
+    end
+  end
+end

data/lib/synapse/event_sourcing/aggregate_root.rb

@@ -0,0 +1,104 @@
+module Synapse
+  module EventSourcing
+    # Mixin for the root entity of an aggregate that is initialized from a historical event stream
+    module AggregateRoot
+      extend ActiveSupport::Concern
+      include Domain::AggregateRoot
+      include Member
+
+      module ClassMethods
+        # Creates a new instance of this aggregate root without calling its initializer and
+        # initializes the state of the aggregate from the given event stream.
+        #
+        # @param [DomainEventStream] stream
+        # @return [AggregateRoot]
+        def new_from_stream(stream)
+          aggregate = allocate
+          aggregate.initialize_from_stream stream
+          aggregate
+        end
+      end
+
+      # @return [Integer] The sequence number of the last committed event
+      def version
+        last_committed_sequence_number
+      end
+
+      # Initializes the state of this aggregate from the given domain event stream
+      #
+      # @raise [RuntimeError] If aggregate has already been initialized
+      # @param [DomainEventStream] stream
+      # @return [undefined]
+      def initialize_from_stream(stream)
+        if uncommitted_event_count > 0
+          raise 'Aggregate has already been initialized'
+        end
+
+        pre_initialize
+
+        last_sequence_number = nil
+
+        stream.each do |event|
+          last_sequence_number = event.sequence_number
+          handle_recursively event
+        end
+
+        initialize_event_container last_sequence_number
+      end
+
+      # Called when a member of the aggregate publishes an event
+      #
+      # This is only meant to be invoked by entities that are members of this aggregate
+      #
+      # @api private
+      # @param [Object] payload
+      # @param [Hash] metadata
+      # @return [undefined]
+      def handle_member_event(payload, metadata = nil)
+        apply payload, metadata
+      end
+
+    protected
+
+      # Hook that is called before the aggregate is initialized
+      # @return [undefined]
+      def pre_initialize; end
+
+      # Creates an event with the given metadata and payload, publishes it using the event
+      # container, and finally handles it locally and recursively down the aggregate.
+      #
+      # @param [Object] payload
+      # @param [Hash] metadata
+      # @return [undefined]
+      def apply(payload, metadata = nil)
+        if id
+          event = publish_event payload, metadata
+          handle_recursively event
+        else
+          # This is a workaround for aggregates that set the aggregate identifier in an event handler
+          event = Domain::DomainEventMessage.build do |b|
+            b.metadata = metadata
+            b.payload = payload
+            b.sequence_number = 0
+          end
+
+          handle_recursively event
+          publish_event payload, metadata
+        end
+      end
+
+      # Handles the event locally and then cascades to any registered child entities
+      #
+      # @param [DomainEventMessage] event
+      # @return [undefined]
+      def handle_recursively(event)
+        handle_event event
+
+        child_entities.each do |entity|
+          entity.aggregate_root = self
+          entity.handle_aggregate_event event
+        end
+      end
+    end
+  end
+end

data/lib/synapse/event_sourcing/conflict_resolver.rb

@@ -0,0 +1,80 @@
+module Synapse
+  module EventSourcing
+    # Represents a mechanism that is capable of detecting conflicts between applied changes
+    # to the aggregate and unseen changes made to the aggregate.
+    class ConflictResolver
+      # Checks the list of changes applied to the aggregate and compares it to the list of
+      # events already applied to the aggregate. If a conflict is detected, this should throw
+      # an exception. Otherwise, the changes will be applied.
+      #
+      # @raise [ConflictingModificationException] If any conflicts were detected
+      # @param [Array] applied_changes List of changes applied to the aggregate
+      # @param [Array] committed_changes List of events that were unexpected by the command handler
+      # @return [undefined]
+      def resolve_conflicts(applied_changes, committed_changes); end
+    end
+
+    # Unit of work listener that detects if there is a conflict before an aggregate is committed
+    # If there is a potential conflict, a conflict resolver determines how to resolve the conflict.
+    class ConflictResolvingUnitOfWorkListener < UnitOfWork::UnitOfWorkListener
+      # @param [AggregateRoot] aggregate
+      # @param [Array] unseen_events
+      # @param [ConflictResolver] conflict_resolver
+      # @return [undefined]
+      def initialize(aggregate, unseen_events, conflict_resolver)
+        @aggregate = aggregate
+        @unseen_events = unseen_events
+        @conflict_resolver = conflict_resolver
+      end
+
+      # @param [UnitOfWork] unit
+      # @param [Array<AggregateRoot>] aggregates
+      # @param [Hash<EventBus, Array>] events
+      # @return [undefined]
+      def on_prepare_commit(unit, aggregates, events)
+        if potential_conflicts?
+          @conflict_resolver.resolve_conflicts @aggregate.uncommitted_events.to_a, @unseen_events
+        end
+      end
+
+    private
+
+      # @return [Boolean]
+      def potential_conflicts?
+        @aggregate.uncommitted_event_count > 0 and
+          @aggregate.version and
+          @unseen_events.size > 0
+      end
+    end
+
+    # Event stream decorator that captures any events that have been applied after the expected
+    # version of an aggregate
+    class CapturingEventStream < Domain::DomainEventStream
+      extend Forwardable
+
+      # @param [DomainEventStream] delegate
+      # @param [Array] unseen_events
+      # @param [Integer] expected_version
+      # @return [undefined]
+      def initialize(delegate, unseen_events, expected_version)
+        @delegate = delegate
+        @unseen_events = unseen_events
+        @expected_version = expected_version
+      end
+
+      # @return [DomainEventMessage]
+      def next_event
+        event = @delegate.next_event
+
+        if @expected_version and event.sequence_number > @expected_version
+          @unseen_events.push event
+        end
+
+        event
+      end
+
+      # Delegators for domain event stream
+      def_delegators :@delegate, :end?, :peek
+    end
+  end
+end

data/lib/synapse/event_sourcing/entity.rb

@@ -0,0 +1,64 @@
+module Synapse
+  module EventSourcing
+    # Mixin for an entity that is part of an event-sourced aggregate
+    #
+    # Instead managing its own published events, the entity relies on being registered to the
+    # aggregate root and using its event container. Events applied to child entities will be
+    # cascaded throughout the entire aggregate.
+    module Entity
+      extend ActiveSupport::Concern
+      include Member
+
+      # Handles an aggregate event locally and then cascades to any registered child entities
+      #
+      # @api private
+      # @param [DomainEventMessage] event
+      # @return [undefined]
+      def handle_aggregate_event(event)
+        handle_recursively event
+      end
+
+      # Registers this entity to the aggregate root
+      #
+      # @api private
+      # @raise [RuntimeError] If entity is registered to a different aggregate root
+      # @param [AggregateRoot] aggregate_root
+      # @return [undefined]
+      def aggregate_root=(aggregate_root)
+        if @aggregate_root and !@aggregate_root.equal? aggregate_root
+          raise 'Entity is registered to a different aggregate root'
+        end
+
+        @aggregate_root = aggregate_root
+      end
+
+    protected
+
+      # Handles the event locally and then cascades to any registered child entities
+      #
+      # @param [DomainEventMessage] event
+      # @return [undefined]
+      def handle_recursively(event)
+        handle_event event
+
+        child_entities.each do |entity|
+          entity.aggregate_root = @aggregate_root
+          entity.handle_aggregate_event event
+        end
+      end
+
+      # Applies the given event to the aggregate and publishes it to the event container
+      #
+      # @param [Object] payload
+      # @param [Hash] metadata
+      # @return [undefined]
+      def apply(payload, metadata = nil)
+        unless @aggregate_root
+          raise 'Entity has not been registered to an aggregate root'
+        end
+
+        @aggregate_root.handle_member_event payload, metadata
+      end
+    end
+  end
+end

data/lib/synapse/event_sourcing/member.rb

@@ -0,0 +1,72 @@
+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
+    module Member
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        # Registers an instance variable as a child entity
+        #
+        # @param [Symbol...] fields
+        # @return [undefined]
+        def child_entity(*fields)
+          fields.each do |field|
+            child_entities.add field.to_s
+          end
+        end
+
+        # Returns a set of symbols referring to child entities
+        # @return [Set]
+        def child_entities
+          @child_entities ||= Set.new
+        end
+      end
+
+    protected
+
+      # Returns an array of the child entities of this aggregate member
+      # @return [Array]
+      def child_entities
+        entities = Array.new
+
+        self.class.child_entities.each do |field|
+          value = instance_variable_get '@' + field
+
+          if value.is_a? Entity
+            entities.push value
+
+          # Hashes
+          elsif value.is_a? Hash
+            entities.concat filter_entities value.each_key
+            entities.concat filter_entities value.each_value
+
+          # Sets, arrays
+          elsif value.is_a? Enumerable
+            entities.concat filter_entities value
+          end
+        end
+
+        entities
+      end
+
+      # If the event is relative to this member, its parameters will be used to change
+      # the state of this member
+      #
+      # @abstract
+      # @param [EventMessage] event
+      # @return [undefined]
+      def handle_event(event); end
+
+    private
+
+      # @param [Array] entities
+      # @return [Array]
+      def filter_entities(entities)
+        entities.select do |entity|
+          entity.is_a? Member
+        end
+      end
+    end
+  end
+end