synapse-core 0.1.2

data/lib/synapse/domain/event_container.rb

@@ -0,0 +1,127 @@
+module Synapse
+  module Domain
+    # Container that tracks uncommitted events published by an aggregate root and its child entities
+    # @api private
+    class EventContainer
+      # @return [Object] The identifier of the aggregate being tracked
+      attr_reader :aggregate_id
+
+      # @return [Integer] The sequence number of the last committed event
+      attr_reader :last_committed_sequence_number
+
+      # Initializes this event container
+      #
+      # @param [Object] aggregate_id
+      #   The identifier of the aggregate being tracked
+      #
+      # @return [undefined]
+      def initialize(aggregate_id)
+        @aggregate_id = aggregate_id
+        @events = Array.new
+        @listeners = Array.new
+      end
+
+      # Registers an event published by the aggregate to this container
+      #
+      # During this process, a domain event message is created. Event registration listeners can
+      # choose to modify or replace the message before it is committed.
+      #
+      # @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 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
+        end
+
+        @listeners.each do |listener|
+          event = listener.call event
+        end
+
+        @last_sequence_number = event.sequence_number
+        @events.push event
+
+        event
+      end
+
+      # Adds an event registration listener to this container
+      #
+      # 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
+      # @return [undefined]
+      def add_registration_listener(listener)
+        @listeners.push listener
+
+        @events.map! do |event|
+          listener.call event
+        end
+      end
+
+      # Sets the last committed sequence number for the container
+      #
+      # @raise [RuntimeError] If events have already been registered to the container
+      # @param [Integer] last_known
+      # @return [undefined]
+      def initialize_sequence_number(last_known)
+        unless @events.empty?
+          raise 'Sequence number must be set before events are registered'
+        end
+
+        @last_committed_sequence_number = last_known
+      end
+
+      # Returns the sequence number of the last event known by this container
+      # @return [Integer]
+      def last_sequence_number
+        if @events.empty?
+          return @last_committed_sequence_number
+        end
+
+        unless @last_sequence_number
+          @last_sequence_number = @events.last.sequence_number
+        end
+
+        @last_sequence_number
+      end
+
+      # Updates the last committed sequence number and clears any uncommitted events and any
+      # event registration listeners
+      #
+      # @return [undefined]
+      def mark_committed
+        @last_committed_sequence_number = @last_sequence_number
+        @events.clear
+        @listeners.clear
+      end
+
+      # Returns an event stream containing the uncommitted events in this container
+      # @return [DomainEventStream]
+      def to_stream
+        SimpleDomainEventStream.new @events
+      end
+
+      # Returns the number of uncommitted events in this container
+      # @return [Integer]
+      def size
+        @events.size
+      end
+
+    private
+
+      # Returns the next sequence number to use for registered events
+      # @return [Integer]
+      def next_sequence_number
+        last_sequence_number ? last_sequence_number.next : 0
+      end
+    end
+  end
+end

data/lib/synapse/domain/message.rb

@@ -0,0 +1,82 @@
+module Synapse
+  module Domain
+    # Represents the occurance of an event in the application that may be of some importance
+    # to another component of the application. It contains the relevant data for other
+    # components to act upon.
+    class EventMessage < Message
+      # The timestamp of when the event was reported
+      # @return [Time]
+      attr_reader :timestamp
+
+      # @param [String] id
+      # @param [Hash] metadata
+      # @param [Object] payload
+      # @param [Time] timestamp
+      # @return [undefined]
+      def initialize(id, metadata, payload, timestamp)
+        super id, metadata, payload
+        @timestamp = timestamp
+      end
+
+      # @return [Class]
+      def self.builder
+        EventMessageBuilder
+      end
+
+    protected
+
+      # @param [EventMessageBuilder] builder
+      # @param [Hash] metadata
+      # @return [undefined]
+      def build_duplicate(builder, metadata)
+        super
+        builder.timestamp = @timestamp
+      end
+    end
+
+    # Message that contains a domain event as a payload that represents a state change in the domain.
+    #
+    # In contrast to a regular event message, this type of message contains the identifier of the
+    # aggregate that reported it. It also contains a sequence number that allows the messages to be placed
+    # in the order they were reported.
+    class DomainEventMessage < EventMessage
+      # The identifier of the aggregate that reported the event
+      # @return [Object]
+      attr_reader :aggregate_id
+
+      # The sequence number of the event in the order of generation
+      # @return [Integer]
+      attr_reader :sequence_number
+
+      # @param [String] id
+      # @param [Hash] metadata
+      # @param [Object] payload
+      # @param [Time] timestamp
+      # @param [Object] aggregate_id
+      # @param [Integer] sequence_number
+      # @return [undefined]
+      def initialize(id, metadata, payload, timestamp, aggregate_id, sequence_number)
+        super id, metadata, payload, timestamp
+
+        @aggregate_id = aggregate_id
+        @sequence_number = sequence_number
+      end
+
+      # @return [Class]
+      def self.builder
+        DomainEventMessageBuilder
+      end
+
+    protected
+
+      # @param [DomainEventMessageBuilder] builder
+      # @param [Hash] metadata
+      # @return [undefined]
+      def build_duplicate(builder, metadata)
+        super
+        builder.aggregate_id = @aggregate_id
+        builder.sequence_number = @sequence_number
+      end
+    end
+  end
+end

data/lib/synapse/domain/message_builder.rb

@@ -0,0 +1,34 @@
+module Synapse
+  module Domain
+    # Message builder capable of producing EventMessage instances
+    class EventMessageBuilder < MessageBuilder
+      # @return [Time]
+      attr_accessor :timestamp
+
+      # @return [EventMessage]
+      def build
+        EventMessage.new @id, @metadata, @payload, @timestamp
+      end
+
+      # @return [undefined]
+      def populate_defaults
+        super
+        @timestamp ||= Time.now
+      end
+    end
+
+    # Message builder capable of producing DomainEventMessage instances
+    class DomainEventMessageBuilder < EventMessageBuilder
+      # @return [Object]
+      attr_accessor :aggregate_id
+
+      # @return [Integer]
+      attr_accessor :sequence_number
+
+      # @return [DomainEventMessage]
+      def build
+        DomainEventMessage.new @id, @metadata, @payload, @timestamp, @aggregate_id, @sequence_number
+      end
+    end
+  end
+end

data/lib/synapse/domain/stream.rb

@@ -0,0 +1,108 @@
+module Synapse
+  module Domain
+    # Represents a historical stream of domain events in chronological order
+    #
+    # @example
+    #   stream = InMemoryDomainEventStream.new events
+    #   until stream.end?
+    #     puts stream.next_event
+    #   end
+    #
+    # @example
+    #   stream = InMemoryDomainEventStream.new events
+    #   stream.each do |event|
+    #     puts event
+    #   end
+    #
+    # @abstract
+    class DomainEventStream
+      # Returns true if the end of the stream has been reached
+      #
+      # @abstract
+      # @return [Boolean]
+      def end?
+        true
+      end
+
+      # Returns the next event in the stream and moves the stream's pointer forward
+      #
+      # @abstract
+      # @return [DomainEventMessage]
+      def next_event; end
+
+      # Returns the next event in the stream without moving the stream's pointer forward
+      #
+      # @abstract
+      # @return [DomainEventMessage]
+      def peek; end
+
+      # Yields the next domain events in the stream until the end of the stream has been reached
+      #
+      # @yield [DomainEventMessage] The next event in the event stream
+      # @return [undefined]
+      def each
+        until end?
+          yield next_event
+        end
+      end
+
+      # Returns the domain events in this stream as an array
+      # @return [Array<DomainEventMessage>]
+      def to_a
+        events = Array.new
+        each do |event|
+          events.push event
+        end
+
+        events
+      end
+
+    protected
+
+      def assert_valid
+        if end?
+          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

data/lib/synapse/duplication.rb

@@ -0,0 +1,60 @@
+module Synapse
+  # Records messages as they are sent to a bus so that duplicates can be tracked and prevented.
+  # Inspired by the de-duplication manager from Lokad.CQRS
+  #
+  # This implementation is thread-safe
+  class DuplicationRecorder
+    def initialize
+      @recorded = Hash.new
+      @lock = Mutex.new
+    end
+
+    # Records the given message so that duplicates can be ignored
+    #
+    # @raise [DuplicationError] If a duplicate message has been detected
+    # @param [Message] message
+    # @return [undefined]
+    def record(message)
+      @lock.synchronize do
+        if @recorded.has_key? message.id
+          raise DuplicationError
+        end
+
+        @recorded.store message.id, Time.now
+      end
+    end
+
+    # Returns true if the given message has been recorded
+    #
+    # @param [Message] message
+    # @return [Boolean]
+    def recorded?(message)
+      @recorded.has_key? message.id
+    end
+
+    # Forgets the given message
+    #
+    # @param [Message] message
+    # @return [undefined]
+    def forget(message)
+      @lock.synchronize do
+        @recorded.delete message.id
+      end
+    end
+
+    # Cleans up messages that are older than the given timestamp
+    #
+    # @param [Time] threshold
+    # @return [undefined]
+    def forget_older_than(threshold)
+      @lock.synchronize do
+        @recorded.delete_if do |message_id, timestamp|
+          timestamp <= threshold
+        end
+      end
+    end
+  end
+
+  # Raised when a duplicate message has been detected by the duplication recorder
+  class DuplicationError < NonTransientError; end
+end

data/lib/synapse/errors.rb

@@ -0,0 +1,13 @@
+module Synapse
+  # Base exception for all Synapse framework-related errors
+  class SynapseError < RuntimeError; end
+
+  # Raised when an error has occured that resulted from misconfiguration
+  class ConfigurationError < SynapseError; end
+
+  # Raised when an error has occured that cannot be resolved with intervention
+  class NonTransientError < SynapseError; end
+
+  # Raised when an error has occured that might be resolved by retrying the operation
+  class TransientError < SynapseError; end
+end

data/lib/synapse/event_bus/event_bus.rb

@@ -0,0 +1,40 @@
+module Synapse
+  module EventBus
+    # Represents a mechanism for event listeners to subscribe to events and for event publishers
+    # to dispatch their events to any interested parties.
+    #
+    # Implementations may or may not dispatch the events to listeners in the dispatching thread.
+    #
+    # @abstract
+    class EventBus
+      # Publishes one or more events to any listeners subscribed to this event bus
+      #
+      # Implementations may treat the given events as a single batch and distribute them as such
+      # to all subscribed event listeners.
+      #
+      # @abstract
+      # @param [EventMessage...] events
+      # @return [undefined]
+      def publish(*events); end
+
+      # Subscribes the given listener to this event bus
+      #
+      # @abstract
+      # @raise [SubscriptionFailedError] If subscription of an event listener failed
+      # @param [EventListener] listener
+      # @return [undefined]
+      def subscribe(listener); end
+
+      # Unsubscribes the given listener from this event bus
+      #
+      # @abstract
+      # @param [EventListener] listener
+      # @return [undefined]
+      def unsubscribe(listener); end
+    end
+
+    # Raised when the subscription of an event listener has not succeeded. Generally, this means that
+    # some precondition set by an event bus implementation for the listener have not been met.
+    class SubscriptionFailedError < NonTransientError; end
+  end
+end