synapse-core 0.1.2

data/lib/synapse/message_builder.rb

@@ -0,0 +1,38 @@
+module Synapse
+  # Builder that is used to easily create and populate messages
+  class MessageBuilder
+    # @return [String]
+    attr_accessor :id
+
+    # @return [Hash]
+    attr_accessor :metadata
+
+    # @return [Object]
+    attr_accessor :payload
+
+    # Convenience method that yields a new builder, populates defaults and returns the newly
+    # built message instance
+    #
+    # @yield [MessageBuilder]
+    # @return [Message]
+    def self.build
+      builder = self.new
+
+      yield builder if block_given?
+
+      builder.populate_defaults
+      builder.build
+    end
+
+    # @return [Message]
+    def build
+      Message.new @id, @metadata, @payload
+    end
+
+    # @return [undefined]
+    def populate_defaults
+      @id ||= IdentifierFactory.instance.generate
+      @metadata ||= Hash.new
+    end
+  end
+end

data/lib/synapse/process_manager/correlation.rb

@@ -0,0 +1,32 @@
+module Synapse
+  module ProcessManager
+    # Combination key and value that is used to correlate incoming events with process instances
+    class Correlation
+      # @return [Symbol]
+      attr_reader :key
+
+      # @return [String]
+      attr_reader :value
+
+      # @param [Symbol] key
+      # @param [String] value
+      # @return [undefined]
+      def initialize(key, value)
+        @key = key.to_sym
+        @value = value.to_s
+      end
+
+      def ==(other)
+        self.class === other and
+          other.key == @key and
+          other.value == @value
+      end
+
+      alias eql? ==
+
+      def hash
+        @key.hash ^ @value.hash
+      end
+    end
+  end
+end

data/lib/synapse/process_manager/correlation_resolver.rb

@@ -0,0 +1,14 @@
+module Synapse
+  module ProcessManager
+    # Represents a mechanism for determining correlations between events and process instances
+    # @abstract
+    class CorrelationResolver
+      # Resolves a correlation from the given event
+      #
+      # @abstract
+      # @param [EventMessage] event
+      # @return [Correlation]
+      def resolve(event); end
+    end
+  end
+end

data/lib/synapse/process_manager/correlation_set.rb

@@ -0,0 +1,58 @@
+module Synapse
+  module ProcessManager
+    # Container that tracks additions and deletions of correlations for a process instance
+    class CorrelationSet
+      extend Forwardable
+      include Enumerable
+
+      # @return [Set]
+      attr_reader :correlations
+
+      # @return [Set]
+      attr_reader :additions
+
+      # @return [Set]
+      attr_reader :deletions
+
+      def initialize
+        @correlations = Set.new
+        @additions = Set.new
+        @deletions = Set.new
+      end
+
+      # Resets the tracked changes
+      # @return [undefined]
+      def commit
+        @additions.clear
+        @deletions.clear
+      end
+
+      # Adds the given correlation to this set, if not previously added
+      #
+      # @param [Correlation] correlation
+      # @return [Boolean]
+      def add(correlation)
+        if @correlations.add? correlation
+          unless @deletions.delete? correlation
+            @additions.add correlation
+          end
+        end
+      end
+
+      # Removes the given correlation from this set, if previously added
+      #
+      # @param [Correlation] correlation
+      # @return [Boolean]
+      def delete(correlation)
+        if @correlations.delete? correlation
+          unless @additions.delete? correlation
+            @deletions.add correlation
+          end
+        end
+      end
+
+      # Delegates enumeration to the backing correlation set
+      def_delegators :@correlations, :each, :size
+    end
+  end
+end

data/lib/synapse/process_manager/process.rb

@@ -0,0 +1,71 @@
+module Synapse
+  module ProcessManager
+    # The term process is used in Enterprise Integration Patterns to describe a mechanism used to
+    # "maintain the state of the sequence and determine the next processing step based on
+    # intermediate results" (Hohpe 279). Processes are also called sagas in some CQRS frameworks.
+    #
+    # @abstract
+    class Process
+      # @return [String] The unique identifier of this process
+      attr_reader :id
+
+      # @return [CorrelationSet] The correlations for this process
+      attr_reader :correlations
+
+      # @return [Boolean] True if this process is active
+      attr_reader :active
+
+      alias active? active
+
+      # @param [String] id
+      # @return [undefined]
+      def initialize(id = nil)
+        unless id
+          id = IdentifierFactory.instance.generate
+        end
+
+        @id = id
+        @correlations = CorrelationSet.new
+        @active = true
+
+        correlate_with :process_id, id
+      end
+
+      # Handles the given event
+      #
+      # The actual result of the processing depends on the implementation of the process.
+      # Implementations are highly discouraged from throwing exceptions.
+      #
+      # @abstract
+      # @param [EventMessage] event
+      # @return [undefined]
+      def handle(event); end
+
+    protected
+
+      # Correlates this process instance with the given key and value
+      #
+      # @param [Symbol] key
+      # @param [String] value
+      # @return [undefined]
+      def correlate_with(key, value)
+        @correlations.add(Correlation.new(key, value))
+      end
+
+      # Dissociates this process instance from the given key and value
+      #
+      # @param [Symbol] key
+      # @param [String] value
+      # @return [undefined]
+      def dissociate_from(key, value)
+        @correlations.delete(Correlation.new(key, value))
+      end
+
+      # Marks this process as finished
+      # @return [undefined]
+      def finish
+        @active = false
+      end
+    end
+  end
+end

data/lib/synapse/repository/errors.rb

@@ -0,0 +1,26 @@
+module Synapse
+  module Repository
+    # Raised when an aggregate could not be found by a repository
+    class AggregateNotFoundError < NonTransientError; end
+
+    # Raised when concurrent access to a repository was detected; the cause is most likely
+    # that two threads were modifying the same aggregate.
+    class ConcurrencyError < TransientError; end
+
+    # Raised when conflicting concurrent modifications are detected
+    class ConflictingModificationError < NonTransientError; end
+
+    # Raised when the version number of the aggregate being loaded didn't match the expected
+    # version number given. This typically means that the aggregate has been modified by another
+    # thread between the moment the data was queried and the command modifying the aggregate
+    # was handled.
+    class ConflictingAggregateVersionError < ConflictingModificationError
+      # @param [AggregateRoot] aggregate
+      # @param [Integer] expected_version
+      # @return [undefined]
+      def initialize(aggregate, expected_version)
+        super 'Aggregate [%s] has version %s, expected %s' % [aggregate.id, aggregate.version, expected_version]
+      end
+    end
+  end
+end

data/lib/synapse/repository/lock_manager.rb

@@ -0,0 +1,40 @@
+module Synapse
+  module Repository
+    # Represents a mechanism for locking aggregates for modification
+    # @abstract
+    class LockManager
+      # Ensures that the current thread holds a valid lock for the given aggregate
+      #
+      # @abstract
+      # @param [AggregateRoot] aggregate
+      # @return [Boolean]
+      def validate_lock(aggregate); end
+
+      # Obtains a lock for an aggregate with the given aggregate identifier. Depending on
+      # the strategy, this method may return immediately or block until a lock is held.
+      #
+      # @abstract
+      # @param [Object] aggregate_id
+      # @return [undefined]
+      def obtain_lock(aggregate_id); end
+
+      # Releases the lock held for an aggregate with the given aggregate identifier. The caller
+      # of this method must ensure a valid lock was requested using {#obtain_lock}. If no lock
+      # was successfully obtained, the behavior of this method is undefined.
+      #
+      # @abstract
+      # @param [Object] aggregate_id
+      # @return [undefined]
+      def release_lock(aggregate_id); end
+    end
+
+    # Implementation of a lock manager that does no locking
+    class NullLockManager < LockManager
+      # @param [AggregateRoot] aggregate
+      # @return [Boolean]
+      def validate_lock(aggregate)
+        true
+      end
+    end
+  end
+end

data/lib/synapse/repository/locking.rb

@@ -0,0 +1,97 @@
+module Synapse
+  module Repository
+    # Partial implementation of a repository that handles integration with a lock manager
+    # @abstract
+    class LockingRepository < Repository
+      # @return [LockManager]
+      attr_reader :lock_manager
+
+      # @param [LockManager] lock_manager
+      # @return [undefined]
+      def initialize(lock_manager)
+        @lock_manager = lock_manager
+        @logger = Logging.logger.new self.class
+      end
+
+      # @raise [AggregateNotFoundError]
+      #   If the aggregate with the given identifier could not be found
+      # @raise [ConflictingModificationError]
+      #   If the expected version doesn't match the aggregate's actual version
+      # @param [Object] aggregate_id
+      # @param [Integer] expected_version If this is nil, no version validation is performed
+      # @return [AggregateRoot]
+      def load(aggregate_id, expected_version = nil)
+        @lock_manager.obtain_lock aggregate_id
+
+        begin
+          aggregate = perform_load aggregate_id, expected_version
+
+          aggregate = register_aggregate aggregate
+          register_listener LockCleaningUnitOfWorkListener.new aggregate_id, @lock_manager
+
+          aggregate
+        rescue
+          @logger.debug 'Excepton raised while loading an aggregate, releasing lock'
+
+          @lock_manager.release_lock aggregate_id
+          raise
+        end
+      end
+
+      # @raise [ArgumentError] If the version of the aggregate is not null
+      # @param [AggregateRoot] aggregate
+      # @return [undefined]
+      def add(aggregate)
+        @lock_manager.obtain_lock aggregate.id
+
+        begin
+          assert_compatible aggregate
+
+          register_aggregate aggregate
+          register_listener LockCleaningUnitOfWorkListener.new aggregate.id, @lock_manager
+        rescue
+          @logger.debug 'Exception raised while adding an aggregate, releasing lock'
+
+          @lock_manager.release_lock aggregate.id
+          raise
+        end
+      end
+
+    protected
+
+      # Fetches the aggregate with the given identifier from the underlying aggregate store
+      #
+      # @abstract
+      # @raise [AggregateNotFoundError]
+      #   If the aggregate with the given identifier could not be found
+      # @raise [ConflictingModificationError]
+      #   If the expected version doesn't match the aggregate's actual version
+      # @param [Object] aggregate_id
+      # @param [Integer] expected_version
+      # @return [AggregateRoot]
+      def perform_load(aggregate_id, expected_version); end
+
+      def logger
+
+      end
+    end
+
+    # Unit of work listener that releases the lock on an aggregate when the unit of work
+    # is cleaning up
+    class LockCleaningUnitOfWorkListener < UnitOfWork::UnitOfWorkListener
+      # @param [Object] aggregate_id
+      # @param [LockManager] lock_manager
+      # @return [undefined]
+      def initialize(aggregate_id, lock_manager)
+        @aggregate_id = aggregate_id
+        @lock_manager = lock_manager
+      end
+
+      # @param [UnitOfWork] unit
+      # @return [undefined]
+      def on_cleanup(unit)
+        @lock_manager.release_lock @aggregate_id
+      end
+    end
+  end
+end

data/lib/synapse/repository/pessimistic_lock_manager.rb

@@ -0,0 +1,61 @@
+module Synapse
+  module Repository
+    # Rough implementation of a pessimistic lock manager using local locks
+    class PessimisticLockManager < LockManager
+      def initialize
+        @aggregates = Hash.new
+        @lock = Mutex.new
+      end
+
+      # @todo Check if current thread holds lock, not just if lock is held
+      # @param [AggregateRoot] aggregate
+      # @return [Boolean]
+      def validate_lock(aggregate)
+        @aggregates.has_key?(aggregate.id) and lock_for(aggregate.id).locked?
+      end
+
+      # @param [Object] aggregate_id
+      # @return [undefined]
+      def obtain_lock(aggregate_id)
+        lock = lock_for aggregate_id
+        lock.lock
+      end
+
+      # @param [Object] aggregate_id
+      # @return [undefined]
+      def release_lock(aggregate_id)
+        unless @aggregates.has_key? aggregate_id
+          raise 'No lock for this identifier was ever obtained'
+        end
+
+        lock = lock_for aggregate_id
+        lock.unlock
+      end
+
+    private
+
+      # @param [Object] aggregate_id
+      # @return [Mutex]
+      def lock_for(aggregate_id)
+        lock = @aggregates[aggregate_id]
+        until lock
+          put_if_absent aggregate_id, Mutex.new
+          lock = @aggregates[aggregate_id]
+        end
+        lock
+      end
+
+      # @param [Object] aggregate_id
+      # @param [Mutex] lock
+      # @return [undefined]
+      def put_if_absent(aggregate_id, lock)
+        @lock.synchronize do
+          unless @aggregates.has_key? aggregate_id
+            @aggregates.store aggregate_id, lock
+          end
+        end
+      end
+
+    end
+  end
+end