event_sourcery 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a6cabf34f27962b52571d80fb0a505186cef6e69
-  data.tar.gz: 3f07fcaf03c74190b2531099f1b4ca10d8312355
+  metadata.gz: c1952be35c93c960587ad23886643f74d4825e18
+  data.tar.gz: 58fbfc8343e6c673b6f003a7d478e05dbdd11fef
 SHA512:
-  metadata.gz: 0a25a29c4d626ae5a179668b4663dc20dc81799948ee38506ce26b3e7b10d7c31e483baf8978507e9cb199b7eda616051b7d8c90e05b5d6af99713430a4fcb83
-  data.tar.gz: 334f2eb26deba53e6459c00caffec74403ee039fdee14d68c45243f889f64690d20082fb98e1006e50ceefaa647d8770090f9d25785b39ddbe9efe97bca01a67
+  metadata.gz: b2aecc3786ef6dfbb7063c50201f0c7b0ff9ad73a368258cc090204c0bd7b865308e9d138475c9f8cdeac3598b6f588de630ccb021335e6f35af1932674a835e
+  data.tar.gz: f423097efb6782559310b3ce0697753338a2eceeadddb9e6a199ca5eebf83fb814985b8f1da76389f34dbda63f05f9edbb64c1c348826462177e2ea6e539d470

data/CHANGELOG.md

@@ -6,6 +6,17 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [0.15.0] - 2017-11-29
+### Added
+- Added in the first version of the yard documentation.
+
+### Changed
+- Improved EventProcessingError messages
+- Fixed typo in constant name `EventSourcery::EventProcessing::ErrorHandlers::ConstantRetry::DEFAULT_RETRY_INTERVAL`
+- Fixed typo in constant name `EventSourcery::EventProcessing::ErrorHandlers::ExponentialBackoffRetry::DEFAULT_RETRY_INTERVAL`
+- Fixed typo in constant name `EventSourcery::EventProcessing::ErrorHandlers::ExponentialBackoffRetry::MAX_RETRY_INTERVAL`
+- Errors of type `Exception` are now logged before being allowed to propagate.
+
 ## [0.14.0] - 2016-6-21
 ### Added
 - Added `Event#to_h` method. This returns a hash of the event attributes.

data/README.md

@@ -56,6 +56,8 @@ The [example EventSourcery application](https://github.com/envato/event_sourcery
 
 Otherwise you will generally need to add both event_sourcery and [event_sourcery-postgres](https://github.com/envato/event_sourcery-postgres) to your application.
 
+If Event Sourcing or CQRS is a new concept to you, we highly recommend you watch [An In-Depth Look at Event Sourcing With CQRS](https://www.youtube.com/watch?v=EqpalkqJD8M&t=2680s). It explores some of the theory behind both Event Sourcing & CQRS and will help you better understand the building blocks of the Event Sourcery framework.
+
 ## Configuration
 
 There are several ways to configure EventSourcery to your liking. The following presents some examples:
@@ -63,7 +65,7 @@ There are several ways to configure EventSourcery to your liking. The following
 ```ruby
 EventSourcery.configure do |config|
   # Add custom reporting of errors occurring during event processing.
-  # One might set up Rollbar here.
+  # One might set up an error reporting service like Rollbar here.
   config.on_event_processor_error = proc { |exception, processor_name| … }
 
   # Enable EventSourcery logging.

data/lib/event_sourcery/aggregate_root.rb

@@ -1,5 +1,55 @@
 module EventSourcery
+  #
+  # EventSourcery::AggregateRoot provides a foundation for writing your own aggregate root classes.
+  # You can use it by including it in your classes, as show in the example code.
+  #
+  # Excerpt from {https://github.com/envato/event_sourcery/blob/master/docs/core-concepts.md EventSourcery Core Concepts} on Aggregates follows:
+  # === Aggregates and Command Handling
+  #
+  #   An aggregate is a cluster of domain objects that can be treated as a single unit.
+  #   Every transaction is scoped to a single aggregate. An aggregate will have one of its component objects be
+  #   the aggregate root. Any references from outside the aggregate should only go to the aggregate root.
+  #   The root can thus ensure the integrity of the aggregate as a whole.
+  #
+  #   — DDD Aggregate
+  #
+  # Clients execute domain transactions against the system by issuing commands against aggregate roots.
+  # The result of these commands is new events being saved to the event store.
+  # A typical EventSourcery application will have one or more aggregate roots with multiple commands.
+  #
+  # The following partial example is taken from the EventSourceryTodoApp.
+  # Refer a more complete example {https://github.com/envato/event_sourcery_todo_app/blob/master/app/aggregates/todo.rb here}.
+  #
+  # @example
+  #   module EventSourceryTodoApp
+  #     module Aggregates
+  #       class Todo
+  #         include EventSourcery::AggregateRoot
+  #
+  #         # An event handler that updates the aggregate's state from a event
+  #         apply TodoAdded do |event|
+  #           @added = true
+  #         end
+  #
+  #         # Method on the aggregate that processes a command and emits an event as a result
+  #         def add(payload)
+  #           raise UnprocessableEntity, "Todo #{id.inspect} already exists" if added
+  #
+  #           apply_event(TodoAdded,
+  #                       aggregate_id: id,
+  #                       body: payload,
+  #           )
+  #        end
+  #
+  #         private
+  #
+  #         attr_reader :added
+  #       end
+  #     end
+  #   end
   module AggregateRoot
+    # Raised when the aggregate doesn't have a method to handle a given event.
+    # Consider implementing one if you get this error.
     UnknownEventError = Class.new(RuntimeError)
 
     def self.included(base)
@@ -10,8 +60,20 @@ module EventSourcery
     end
 
     module ClassMethods
+      # Collection of event handlers for the events that this aggregate cares about
+      #
+      # @return Hash
       attr_reader :event_handlers
 
+      # Register an event handler for the specified event(s)
+      #
+      # @param event_classes one or more event types for which the handler is for
+      # @param block the event handler
+      #
+      # @example
+      #   apply TodoAdded do |event|
+      #     @added = true
+      #   end
       def apply(*event_classes, &block)
         event_classes.each do |event_class|
           @event_handlers[event_class.type] << block
@@ -19,6 +81,11 @@ module EventSourcery
       end
     end
 
+    # Load an aggregate instance based on the given ID and events
+    #
+    # @param id [String] ID (a UUID represented as a string) of the aggregate instance to be loaded
+    # @param events [Array] Events from which the aggregate's current state will be formed
+    # @param on_unknown_event [Proc] Optional. The proc to be run if an unknown event type (for which no event handler is registered using {ClassMethods#apply}) is to be loaded.
     def initialize(id, events, on_unknown_event: EventSourcery.config.on_unknown_event)
       @id = id.to_str
       @version = 0
@@ -27,8 +94,20 @@ module EventSourcery
       load_history(events)
     end
 
-    attr_reader :changes, :version
+    # Collection of new events that are yet to be persisted
+    #
+    # @return Array
+    attr_reader :changes
 
+    # Current version of the aggregate. This is the same as the number of events
+    # currently loaded by the aggregate.
+    #
+    # @return Integer
+    attr_reader :version
+
+    # Clears any changes present in {changes}
+    #
+    # @api private
     def clear_changes
       @changes.clear
     end

data/lib/event_sourcery/config.rb

@@ -2,37 +2,64 @@ require 'logger'
 
 module EventSourcery
   class Config
-    attr_accessor :on_unknown_event,
-                  :on_event_processor_error,
-                  :event_type_serializer,
-                  :error_handler_class
+    # The default Proc to be run when an aggregate loads an event type that
+    # it doesn't know how to handle.
+    # What's specified here can be overridden when instantiating an aggregate
+    # instance. {AggregateRoot#initialize}
+    #
+    # If no custom Proc is set, by default behaviour is to raise {AggregateRoot::UnknownEventError}
+    #
+    # @return Proc
+    attr_accessor :on_unknown_event
+
+    # A Proc to be executed on an event processor error.
+    # App specific custom logic can be provided.
+    # i.e. report to an error reporting service like Rollbar.
+    #
+    # @return Proc
+    attr_accessor :on_event_processor_error
+
+    # @return EventStore::EventTypeSerializers::Underscored
+    attr_accessor :event_type_serializer
+
+    # @return EventProcessing::ErrorHandlers::ConstantRetry
+    attr_accessor :error_handler_class
 
     attr_writer :logger,
                 :event_body_serializer,
                 :event_builder
 
+    # @api private
     def initialize
       @on_unknown_event = proc { |event, aggregate|
         raise AggregateRoot::UnknownEventError, "#{event.type} is unknown to #{aggregate.class.name}"
       }
       @on_event_processor_error = proc { |exception, processor_name|
-        # app specific custom logic ie. report to rollbar
+        # app specific custom logic ie. report to an error reporting service like Rollbar.
       }
       @event_store = nil
       @event_type_serializer = EventStore::EventTypeSerializers::Underscored.new
       @error_handler_class = EventProcessing::ErrorHandlers::ConstantRetry
     end
 
+    # Logger instance used by EventSourcery.
+    # By default EventSourcery will log to STDOUT with a log level of Logger::DEBUG
     def logger
       @logger ||= ::Logger.new(STDOUT).tap do |logger|
         logger.level = Logger::DEBUG
       end
     end
 
+    # The event builder used by an event store to build event instances.
+    # By default {EventStore::EventBuilder} will be used.
+    # Provide a custom builder here to change how an event is built.
     def event_builder
       @event_builder || EventStore::EventBuilder.new(event_type_serializer: @event_type_serializer)
     end
 
+    # The event body serializer used by the default event builder
+    # ({EventStore::EventBuilder}). By default {EventBodySerializer} will be used.
+    # Provide a custom serializer here to change how the event body is serialized.
     def event_body_serializer
       @event_body_serializer ||= EventBodySerializer.new
         .add(Hash, EventBodySerializer::HashSerializer)

data/lib/event_sourcery/errors.rb

@@ -6,14 +6,19 @@ module EventSourcery
   AtomicWriteToMultipleAggregatesNotSupported = Class.new(Error)
 
   class EventProcessingError < Error
-    attr_reader :event
+    attr_reader :event, :processor
 
-    def initialize(event)
+    def initialize(event:, processor:)
       @event = event
+      @processor = processor
     end
 
     def message
-      cause.message if cause
+      parts = []
+      parts << "#<#{processor.class} @@processor_name=#{processor.processor_name.inspect}>"
+      parts << "#<#{event.class} @id=#{event.id.inspect}, @uuid=#{event.uuid.inspect}, @type=#{event.type.inspect}>"
+      parts << "#<#{cause.class}: #{cause.message}>"
+      parts.join("\n") + "\n"
     end
   end
 end

data/lib/event_sourcery/event.rb

@@ -1,7 +1,11 @@
 module EventSourcery
+  # Represents an Event
   class Event
     include Comparable
 
+    # Event type
+    #
+    # Will return `nil` if called on an instance of {EventSourcery::Event}.
     def self.type
       unless self == Event
         EventSourcery.config.event_type_serializer.serialize(self)
@@ -10,6 +14,42 @@ module EventSourcery
 
     attr_reader :id, :uuid, :aggregate_id, :type, :body, :version, :created_at, :correlation_id, :causation_id
 
+    # @!attribute [r] id
+    # @return [Integer] unique identifier at the persistent layer
+
+    # @!attribute [r] uuid
+    # @return [String] unique identifier (UUID) for this event.
+
+    # @!attribute [r] aggregate_id
+    # @return [String] aggregate instance UUID to which this event belongs to.
+
+    # @!attribute [r] type
+    # @return event type
+
+    # @!attribute [r] body
+    # @return [Hash] Content of the event body.
+
+    # @!attribute [r] version
+    # @return [String] event version. Used by some event stores to guard against concurrency errors.
+
+    # @!attribute [r] created_at
+    # @return [Time] Created at timestamp (in UTC) for the event.
+
+    # @!attribute [r] correlation_id
+    # @return [String] UUID attached to the event that allows reference to a particular transaction or event chain. This value is often supplied as part of a command issued by clients.
+
+    # @!attribute [r] causation_id
+    # @return [String] UUID of the event that caused this event.
+
+    #
+    # @param id [Integer] Optional. Unique identifier at the persistent layer. By default this will be set by the underlying persistence layer when persisting the event.
+    # @param uuid [String] UUID as a string. Optional. Unique identifier for this event. A random UUID will be generated by default.
+    # @param aggregate_id [String] UUID as a string. Aggregate instance UUID to which this event belongs to.
+    # @param type [Class] Optional. Event type. {Event.type} will be used by default.
+    # @param version [String] Optional. Event's aggregate version. Used by some event stores to guard against concurrency errors.
+    # @param created_at [Time] Optional. Created at timestamp (in UTC) for the event.
+    # @param correlation_id [String] Optional. UUID attached to the event that allows reference to a particular transaction or event chain. This value is often supplied as part of a command issued by clients.
+    # @param causation_id [String] Optional. UUID of the event that caused this event.
     def initialize(id: nil,
                    uuid: SecureRandom.uuid,
                    aggregate_id: nil,
@@ -30,6 +70,7 @@ module EventSourcery
       @causation_id = causation_id
     end
 
+    # Is this event persisted?
     def persisted?
       !id.nil?
     end
@@ -46,10 +87,30 @@ module EventSourcery
       id <=> other.id if other.is_a? Event
     end
 
+    # create a new event identical to the old event except for the provided changes
+    #
+    # @param attributes [Hash]
+    # @return Event
+    # @example
+    #     old_event = EventSourcery::Event.new(type: "item_added", causation_id: nil)
+    #     new_event = old_event.with(causation_id: "05781bd6-796a-4a58-8573-b109f683fd99")
+    #
+    #     new_event.type # => "item_added"
+    #     new_event.causation_id # => "05781bd6-796a-4a58-8573-b109f683fd99"
+    #
+    #     old_event.type # => "item_added"
+    #     old_event.causation_id # => nil
+    #
+    #     # Of course, with can accept any number of event attributes:
+    #
+    #     new_event = old_event.with(id: 42, version: 77, body: { 'attr' => 'value' })
     def with(**attributes)
       self.class.new(**to_h.merge!(attributes))
     end
 
+    # returns a hash of the event attributes
+    #
+    # @return Hash
     def to_h
       {
         id:             id,

data/lib/event_sourcery/event_body_serializer.rb

@@ -1,5 +1,10 @@
 module EventSourcery
+  # EventBodySerializer is used for serializing event bodies when persisting events.
   class EventBodySerializer
+    # Serialize the given event body, with the default or the provided, serializer
+    #
+    # @param event_body event body to be serialized
+    # @param serializer Optional. Serializer to be used. By default {Config#event_body_serializer EventSourcery.config.event_body_serializer} will be used.
     def self.serialize(event_body,
                        serializer: EventSourcery.config.event_body_serializer)
       serializer.serialize(event_body)
@@ -9,16 +14,25 @@ module EventSourcery
       @serializers = Hash.new(IdentitySerializer)
     end
 
+    # Register a serializer (instance or block) for the specified type
+    #
+    # @param type The type for which the provided serializer will be used for
+    # @param serializer Optional. A serializer instance for the given type
+    # @param block_serializer [Proc] Optional. A block that performs the serialization
     def add(type, serializer = nil, &block_serializer)
       @serializers[type] = serializer || block_serializer
       self
     end
 
+    # Serialize the given event body
+    #
+    # @param object event body to be serialized
     def serialize(object)
       serializer = @serializers[object.class]
       serializer.call(object, &method(:serialize))
     end
 
+    # Default serializer for Hash objects
     module HashSerializer
       def self.call(hash, &serialize)
         hash.each_with_object({}) do |(key, value), memo|
@@ -27,12 +41,14 @@ module EventSourcery
       end
     end
 
+    # Default serializer for Array objects
     module ArraySerializer
       def self.call(array, &serialize)
         array.map(&serialize)
       end
     end
 
+    # Default catch all implementation for serializing any object
     module IdentitySerializer
       def self.call(object)
         object

data/lib/event_sourcery/event_processing/error_handlers/constant_retry.rb

@@ -1,14 +1,21 @@
 module EventSourcery
   module EventProcessing
     module ErrorHandlers
+      # Strategies for error handling.
       class ConstantRetry
         include EventSourcery::EventProcessing::ErrorHandlers::ErrorHandler
-        DEFAULT_RETRY_INVERAL = 1
+
+        # The retry interval used with {with_error_handling}.
+        #
+        # @api private
+        DEFAULT_RETRY_INTERVAL = 1
+        
         def initialize(processor_name:)
           @processor_name = processor_name
-          @retry_interval = DEFAULT_RETRY_INVERAL
+          @retry_interval = DEFAULT_RETRY_INTERVAL
         end
 
+        # Will yield the block and attempt to retry after a defined retry interval {DEFAULT_RETRY_INTERVAL}.
         def with_error_handling
           yield
         rescue => error

data/lib/event_sourcery/event_processing/error_handlers/error_handler.rb

@@ -2,10 +2,13 @@ module EventSourcery
   module EventProcessing
     module ErrorHandlers
       module ErrorHandler
+        # The default with_error_handling method. Will always raise NotImplementedError
+        #
+        # @raise [NotImplementedError]
         def with_error_handling
           raise NotImplementedError, 'Please implement #with_error_handling method'
         end
-        
+
         private
 
         def report_error(error)

data/lib/event_sourcery/event_processing/error_handlers/exponential_backoff_retry.rb

@@ -3,14 +3,23 @@ module EventSourcery
     module ErrorHandlers
       class ExponentialBackoffRetry
         include EventSourcery::EventProcessing::ErrorHandlers::ErrorHandler
-        DEFAULT_RETRY_INVERAL = 1
-        MAX_RETRY_INVERVAL = 64
+
+        # The starting value for the retry interval used with {with_error_handling}.
+        #
+        # @api private
+        DEFAULT_RETRY_INTERVAL = 1
+
+        # The maximum retry interval value to be used with {with_error_handling}.
+        #
+        # @api private
+        MAX_RETRY_INTERVAL = 64
 
         def initialize(processor_name:)
           @processor_name = processor_name
-          @retry_interval = DEFAULT_RETRY_INVERAL
+          @retry_interval = DEFAULT_RETRY_INTERVAL
         end
 
+        # Will yield the block and attempt to retry in an exponential backoff.
         def with_error_handling
           yield
         rescue => error
@@ -25,13 +34,13 @@ module EventSourcery
         def update_retry_interval(error)
           if error.instance_of?(EventSourcery::EventProcessingError)
             if @error_event_uuid == error.event.uuid
-              @retry_interval *= 2 if @retry_interval < MAX_RETRY_INVERVAL
+              @retry_interval *= 2 if @retry_interval < MAX_RETRY_INTERVAL
             else
               @error_event_uuid = error.event.uuid
-              @retry_interval = DEFAULT_RETRY_INVERAL
+              @retry_interval = DEFAULT_RETRY_INTERVAL
             end
           else
-            @retry_interval = DEFAULT_RETRY_INVERAL
+            @retry_interval = DEFAULT_RETRY_INTERVAL
           end
         end
       end

data/lib/event_sourcery/event_processing/error_handlers/no_retry.rb

@@ -7,6 +7,7 @@ module EventSourcery
           @processor_name = processor_name
         end
 
+        # Will yield the block and exit the process if an error is raised.
         def with_error_handling
           yield
         rescue => error

data/lib/event_sourcery/event_processing/esp_process.rb

@@ -8,7 +8,9 @@ module EventSourcery
         @event_source = event_source
         @subscription_master = subscription_master
       end
-
+      
+      # This will start the Event Stream Processor which will subscribe
+      # to the event stream source.
       def start
         name_process
         error_handler.with_error_handling do
@@ -16,6 +18,9 @@ module EventSourcery
           subscribe_to_event_stream
           EventSourcery.logger.info("Stopping #{@event_processor.processor_name}")
         end
+      rescue Exception => e
+        EventSourcery.logger.error(e)
+        raise e
       end
 
       private

data/lib/event_sourcery/event_processing/esp_runner.rb

@@ -15,6 +15,7 @@ module EventSourcery
         @exit_status = true
       end
 
+      # Start each Event Stream Processor in a new child process.
       def start!
         with_logging do
           start_processes
@@ -73,6 +74,7 @@ module EventSourcery
         send_signal_to_remaining_processes(:KILL)
       end
 
+
       def send_signal_to_remaining_processes(signal)
         Process.kill(signal, *@pids) unless all_processes_terminated?
       rescue Errno::ESRCH

data/lib/event_sourcery/event_processing/event_stream_processor.rb

@@ -18,6 +18,12 @@ module EventSourcery
       end
 
       module ProcessHandler
+        # Handler that processes the given event.
+        #
+        # @raise [EventProcessingError] error raised due to processing isssues
+        # @raise [UnableToProcessEventError] raised if unable to process event type
+        #
+        # @param event [Event] the event to process
         def process(event)
           @_event = event
           handlers = self.class.event_handlers[event.type]
@@ -34,28 +40,46 @@ module EventSourcery
           end
           @_event = nil
         rescue
-          raise EventProcessingError.new(event)
+          raise EventProcessingError.new(event: event, processor: self)
         end
       end
 
       module ClassMethods
+
+        # @attr_reader processes_event_types [Array] Process Event Types
+        # @attr_reader event_handlers [Hash] Hash of handler blocks keyed by event
         attr_reader :processes_event_types, :event_handlers
 
+        # Registers the event types to process.
+        #
+        # @param event_types a collection of event types to process
         def processes_events(*event_types)
           @processes_event_types = Array(@processes_event_types) | event_types.map(&:to_s)
         end
 
+        # Indicate that this class can process all event types. Note that you need to call this method if you
+        # intend to process all event types, without calling {ProcessHandler#process} for each event type.
         def processes_all_events
           define_singleton_method :processes? do |_|
             true
           end
         end
 
+        # Can this class process this event type.
+        # If you use process_all_events this will always return true
+        #
+        # @param event_type the event type to check
+        #
+        # @return [True, False]
         def processes?(event_type)
           processes_event_types &&
             processes_event_types.include?(event_type.to_s)
         end
 
+        # Set the name of the processor.
+        # Returns the class name if no name is given.
+        #
+        # @param name [String] the name of the processor to set
         def processor_name(name = nil)
           if name
             @processor_name = name
@@ -64,6 +88,10 @@ module EventSourcery
           end
         end
 
+        # Process the events for the given event types with the given block.
+        #
+        # @param event_classes the event type classes to process
+        # @param block the code block used to process
         def process(*event_classes, &block)
           event_classes.each do |event_class|
             processes_events event_class.type
@@ -72,30 +100,42 @@ module EventSourcery
         end
       end
 
+      # Calls processes_event_types method on the instance class
       def processes_event_types
         self.class.processes_event_types
       end
 
+      # Set up the event tracker
       def setup
         tracker.setup(processor_name)
       end
 
+      # Reset the event tracker
       def reset
         tracker.reset_last_processed_event_id(processor_name)
       end
 
+      # Return the last processed event id
+      #
+      # @return [Int] the id of the last processed event
       def last_processed_event_id
         tracker.last_processed_event_id(processor_name)
       end
 
+      # Calls processor_name method on the instance class
       def processor_name
         self.class.processor_name
       end
 
+      # Calls processes? method on the instance class
       def processes?(event_type)
         self.class.processes?(event_type)
       end
 
+      # Subscribe to the given event source.
+      #
+      # @param event_source the event source to subscribe to
+      # @param subscription_master [SignalHandlingSubscriptionMaster]
       def subscribe_to(event_source, subscription_master: EventStore::SignalHandlingSubscriptionMaster.new)
         setup
         event_source.subscribe(from_id: last_processed_event_id + 1,
@@ -105,6 +145,7 @@ module EventSourcery
         end
       end
 
+      # @attr_writer tracker the tracker for the class
       attr_accessor :tracker
 
       private