sequent 3.4.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a5a7fbe148700d4a9dcc94486ae59c237043bd824cac58cc40d65ca61f6c86e
-  data.tar.gz: da13d594f5145355f85a9e02877b9c9137b5fc66757c4b1a1c318801f87065eb
+  metadata.gz: 11621c1f62780395fc4954a6a5180aa027eb8a26a88d42da6419b20f9e312122
+  data.tar.gz: 855d52912a637416cfdaf66fad0bdf15d9ea4f4474e8896e7441dc8d56afa98b
 SHA512:
-  metadata.gz: effaa48077d9f375b804f35dfd1b51165cf919fdafeb2677a03173d8678228b8e6b3d08664ad23189cf88cbe2b3e54c8c62676cc9f70498c7a01f4c303434ba9
-  data.tar.gz: 456a50e34447a5c1dd429c470b4ba4e75cb7f1b6cf7bb3392da5577057097de79b1b2331d09dd896640aaba4424d347cc3af7bf8aac660195fd4c5dec562d6c3
+  metadata.gz: c45c07e3e9ac5a4d52bb82dfb7bd76c7096115eb97f0f87477ee99b95eec513a68e67f422a2fb76d23626596c206a5c881f14afce281129e071b3c383ba36979
+  data.tar.gz: de31f973652d7bcc75f8dc6964039d139b464c59e2bd0ace6c4dbf000b017d708dd667fcf6cce90c925c7582361f0dd6a9d53f9abc18ed46c8ccae2c1461fcde

data/lib/sequent/configuration.rb

@@ -28,6 +28,8 @@ module Sequent
 
     DEFAULT_STRICT_CHECK_ATTRIBUTES_ON_APPLY_EVENTS = false
 
+    DEFAULT_ERROR_LOCALE_RESOLVER = -> { I18n.locale || :en }
+
     attr_accessor :aggregate_repository
 
     attr_accessor :event_store,
@@ -51,6 +53,7 @@ module Sequent
 
     attr_accessor :logger
 
+    attr_accessor :error_locale_resolver
 
     attr_accessor :migration_sql_files_directory,
                   :view_schema_name,
@@ -109,6 +112,7 @@ module Sequent
       self.strict_check_attributes_on_apply_events = DEFAULT_STRICT_CHECK_ATTRIBUTES_ON_APPLY_EVENTS
 
       self.logger = Logger.new(STDOUT).tap {|l| l.level = Logger::INFO }
+      self.error_locale_resolver = DEFAULT_ERROR_LOCALE_RESOLVER
     end
 
     def replayed_ids_table_name=(table_name)

data/lib/sequent/core/aggregate_repository.rb

@@ -105,6 +105,11 @@ module Sequent
 
       # Gets all uncommitted_events from the 'registered' aggregates
       # and stores them in the event store.
+      #
+      # The events given to the EventStore are ordered in loading order
+      # of the different AggregateRoot's. So Events are stored
+      # (and therefore published) in order in which they are `apply`-ed per AggregateRoot.
+      #
       # The command is 'attached' for traceability purpose so we can see
       # which command resulted in which events.
       #

data/lib/sequent/core/command.rb

@@ -7,7 +7,15 @@ require_relative 'helpers/mergable'
 
 module Sequent
   module Core
-    # Base command
+    #
+    # Base class for all Command's.
+    #
+    # Commands form the API of your domain. They are
+    # simple data objects with descriptive names
+    # of what they want to achieve. E.g. `SendInvoice`.
+    #
+    # BaseCommand uses `ActiveModel::Validations` for
+    # validations
     class BaseCommand
       include ActiveModel::Validations,
               Sequent::Core::Helpers::Copyable,
@@ -40,6 +48,9 @@ module Sequent
       end
     end
 
+    #
+    # Utility class containing all subclasses of BaseCommand
+    #
     class Commands
       class << self
         def commands
@@ -60,7 +71,7 @@ module Sequent
       end
     end
 
-    # Most commonly used command
+    # Most commonly used Command
     # Command can be instantiated just by using:
     #
     #   Command.new(aggregate_id: "1", user_id: "joe")

data/lib/sequent/core/command_service.rb

@@ -4,23 +4,29 @@ require_relative 'current_event'
 module Sequent
   module Core
     #
-    # Single point in the application where subclasses of Sequent::Core::BaseCommand
-    # are executed. This will initiate the entire flow of:
+    # Single point in the application to get something done in Sequent.
+    # The CommandService handles all subclasses Sequent::Core::BaseCommand. Most common
+    # use is to subclass `Sequent::Command`.
     #
-    # * Validate command
-    # * Call correct Sequent::Core::BaseCommandHandler
-    # * CommandHandler decides which Sequent::Core::AggregateRoot (s) to call
-    # * Events are stored in the Sequent::Core::EventStore
-    # * Unit of Work is cleared
+    # The CommandService is available via the shortcut method `Sequent.command_service`
+    #
+    # To use the CommandService please use:
+    #
+    #   Sequent.command_service.execute_commands(...)
     #
     class CommandService
+      #
       # Executes the given commands in a single transactional block as implemented by the +transaction_provider+
       #
-      # For each command:
+      # For each Command:
+      #
+      # * Validate command
+      # * Call Sequent::CommandHandler's listening to the given Command
+      # * Store and publish Events
+      # * Any new Command's (from e.g. workflows) are queued for processing in the same transaction
+      #
+      # At the end the transaction is committed and the AggregateRepository's Unit of Work is cleared.
       #
-      # * All filters are executed. Any exception raised will rollback the transaction and propagate up
-      # * If the command is valid all +command_handlers+ that +handles_message?+ is invoked
-      # * The +repository+ commits the command and all uncommitted_events resulting from the command
       def execute_commands(*commands)
         commands.each do |command|
           if command.respond_to?(:event_aggregate_id) && CurrentEvent.current
@@ -33,6 +39,7 @@ module Sequent
       end
 
       def remove_event_handler(clazz)
+        warn "[DEPRECATION] `remove_event_handler` is deprecated"
         event_store.remove_event_handler(clazz)
       end
 
@@ -54,9 +61,16 @@ module Sequent
       end
 
       def process_command(command)
+        fail ArgumentError, 'command is required' if command.nil?
+
+        Sequent.logger.debug("[CommandService] Processing command #{command.class}")
+
         filters.each { |filter| filter.execute(command) }
 
-        raise CommandNotValid.new(command) unless command.valid?
+        I18n.with_locale(Sequent.configuration.error_locale_resolver.call) do
+          raise CommandNotValid.new(command) unless command.valid?
+        end
+
         parsed_command = command.parse_attrs_to_correct_types
         command_handlers.select { |h| h.class.handles_message?(parsed_command) }.each { |h| h.handle_message parsed_command }
         repository.commit(parsed_command)

data/lib/sequent/core/event_publisher.rb

@@ -46,6 +46,10 @@ module Sequent
       end
 
       def process_event(event)
+        fail ArgumentError, 'event is required' if event.nil?
+
+        Sequent.logger.debug("[EventPublisher] Publishing event #{event.class}")
+
         configuration.event_handlers.each do |handler|
           begin
             handler.handle_message event

data/lib/sequent/core/event_store.rb

@@ -33,10 +33,18 @@ module Sequent
       # Stores the events in the EventStore and publishes the events
       # to the registered event_handlers.
       #
-      # Streams_with_Events is an enumerable of pairs from
-      # `StreamRecord` to arrays of uncommitted `Event`s.
+      # The events are published according to the order in
+      # the tail of the given `streams_with_events` array pair.
+      #
+      # @param command The command that caused the Events
+      # @param streams_with_events is an enumerable of pairs from
+      #   `StreamRecord` to arrays ordered uncommitted `Event`s.
       #
       def commit_events(command, streams_with_events)
+        fail ArgumentError, "command is required" if command.nil?
+
+        Sequent.logger.debug("[EventStore] Committing events for command #{command.class}")
+
         store_events(command, streams_with_events)
         publish_events(streams_with_events.flat_map { |_, events| events })
       end

data/lib/sequent/core/helpers/attribute_support.rb

@@ -9,16 +9,30 @@ require_relative 'association_validator'
 module Sequent
   module Core
     module Helpers
-      # Provides functionality for defining attributes with their types
+      # Provides functionality for defining attributes with their types.
       #
-      # Since our Commands and ValueObjects are not backed by a database like e.g. rails
+      # Since our Commands and ValueObjects are not backed by a database like e.g. Rails
       # we can not infer their types. We need the types to be able to parse from and to json.
-      # We could have stored te type information in the json, but we didn't.
-      #
       # You typically do not need to include this module in your classes. If you extend from
-      # Sequent::Core::ValueObject, Sequent::Core::Event or Sequent::Core::BaseCommand you will
+      # Sequent::ValueObject, Sequent::Event or Sequent::Command you will
       # get this functionality for free.
       #
+      # Example:
+      #
+      #   attrs name: String, age: Integer, born: Date
+      #
+      # Currently Sequent supports the following types:
+      #
+      # - String
+      # - Integer
+      # - Boolean
+      # - Date
+      # - DateTime
+      # - Subclasses of Sequent::ValueObject
+      # - Lists defined as `array(String)`
+      # - BigDecimal
+      # - Sequent::Secret
+      #
       module AttributeSupport
         class UnknownAttributeError < StandardError; end
 

data/lib/sequent/core/helpers/mergable.rb

@@ -8,6 +8,7 @@ module Sequent
       module Mergable
 
         def merge!(attrs = {})
+          warn "[DEPRECATION] `merge!` is deprecated. Please use `copy` instead. This method will no longer be included in the next version of Sequent. You can still use it but you will have to include the module `Sequent::Core::Helpers::Mergable` yourself."
           attrs.each do |name, value|
             self.send("#{name}=", value)
           end

data/lib/sequent/sequent.rb

@@ -64,6 +64,10 @@ module Sequent
     configuration.aggregate_repository
   end
 
+  def self.dry_run(*commands)
+    Sequent::Util::DryRun.these_commands(commands)
+  end
+
   # Shortcut classes for easy usage
   Event = Sequent::Core::Event
   Command = Sequent::Core::Command

data/lib/sequent/util/dry_run.rb

@@ -0,0 +1,191 @@
+require_relative '../test/command_handler_helpers'
+
+module Sequent
+  module Util
+    ##
+    # Dry run provides the ability to inspect what would
+    # happen if the given commands would be executed
+    # without actually committing the results.
+    # You can inspect which commands are executed
+    # and what the resulting events would be
+    # with theSequent::Projector's and Sequent::Workflow's
+    # that would be invoked (without actually invoking them).
+    #
+    # Since the Workflow's are not actually invoked new commands
+    # resulting from this Workflow will of course not be in the result.
+    #
+    # Caution: Since the Sequent Configuration is shared between threads this method
+    # is not Thread safe.
+    #
+    # Example usage:
+    #
+    #   result = Sequent.dry_run(create_foo_command, ping_foo_command)
+    #
+    #   result.print(STDOUT)
+    #
+    module DryRun
+      EventInvokedHandler = Struct.new(:event, :handler)
+
+      ##
+      # Proxies the given EventStore implements commit_events
+      # that instead of publish and store just publishes the events.
+      class EventStoreProxy
+        attr_reader :command_with_events, :event_store
+
+        delegate :load_events_for_aggregates,
+          :load_events,
+          :publish_events,
+          :stream_exists?,
+          to: :event_store
+
+        def initialize(result)
+          @event_store = Sequent::Test::CommandHandlerHelpers::FakeEventStore.new
+          @command_with_events = {}
+          @result = result
+        end
+
+        def commit_events(command, streams_with_events)
+          event_store.commit_events(command, streams_with_events)
+
+          new_events = streams_with_events.flat_map { |_, events| events }
+          @result.published_command_with_events(command, new_events)
+        end
+      end
+
+      ##
+      # Records which Projector's and Workflow's are executed
+      #
+      class RecordingEventPublisher < Sequent::Core::EventPublisher
+        attr_reader :projectors, :workflows
+
+        def initialize(result)
+          @result = result
+        end
+
+        def process_event(event)
+          Sequent.configuration.event_handlers.each do |handler|
+            next unless handler.class.handles_message?(event)
+
+            if handler.is_a?(Sequent::Workflow)
+              @result.invoked_workflow(EventInvokedHandler.new(event, handler.class))
+            elsif handler.is_a?(Sequent::Projector)
+              @result.invoked_projector(EventInvokedHandler.new(event, handler.class))
+            else
+              fail "Unrecognized event_handler #{handler.class} called for event #{event.class}"
+            end
+          rescue
+            raise PublishEventError.new(handler.class, event)
+          end
+        end
+      end
+
+      ##
+      # Contains the result of a dry run.
+      #
+      # @see #tree
+      # @see #print
+      #
+      class Result
+        EventCalledHandlers = Struct.new(:event, :projectors, :workflows)
+
+        def initialize
+          @command_with_events = {}
+          @event_invoked_projectors = []
+          @event_invoked_workflows = []
+        end
+
+        def invoked_projector(event_invoked_handler)
+          event_invoked_projectors << event_invoked_handler
+        end
+
+        def invoked_workflow(event_invoked_handler)
+          event_invoked_workflows << event_invoked_handler
+        end
+
+        def published_command_with_events(command, events)
+          command_with_events[command] = events
+        end
+
+        ##
+        # Returns the command with events as a tree structure.
+        #
+        # {
+        #   command => [
+        #     EventCalledHandlers,
+        #     EventCalledHandlers,
+        #     EventCalledHandlers,
+        #   ]
+        # }
+        #
+        # The EventCalledHandlers contains an Event with the
+        # lists of `Sequent::Projector`s and `Sequent::Workflow`s
+        # that were called.
+        #
+        def tree
+          command_with_events.reduce({}) do |memo, (command, events)|
+            events_to_handlers = events.map do |event|
+              for_current_event = ->(pair) { pair.event == event }
+              EventCalledHandlers.new(
+                event,
+                event_invoked_projectors.select(&for_current_event).map(&:handler),
+                event_invoked_workflows.select(&for_current_event).map(&:handler),
+              )
+            end
+            memo[command] = events_to_handlers
+            memo
+          end
+        end
+
+        ##
+        # Prints the output from #tree to the given `io`
+        #
+        def print(io)
+          tree.each_with_index do |(command, event_called_handlerss), index|
+            io.puts "+++++++++++++++++++++++++++++++++++" if index == 0
+            io.puts "Command: #{command.class} resulted in #{event_called_handlerss.length} events"
+            event_called_handlerss.each_with_index do |event_called_handlers, i|
+              io.puts "" if i > 0
+              io.puts "-- Event #{event_called_handlers.event.class} was handled by:"
+              io.puts "-- Projectors: [#{event_called_handlers.projectors.join(', ')}]"
+              io.puts "-- Workflows: [#{event_called_handlers.workflows.join(', ')}]"
+            end
+
+            io.puts "+++++++++++++++++++++++++++++++++++"
+          end
+        end
+
+        private
+
+        attr_reader :command_with_events, :event_invoked_projectors, :event_invoked_workflows
+      end
+
+      ##
+      # Main method of the DryRun.
+      #
+      # Caution: Since the Sequent Configuration is changed and is shared between threads this method
+      # is not Thread safe.
+      #
+      # After invocation the sequent configuration is reset to the state it was before
+      # invoking this method.
+      #
+      # @param commands - the commands to dry run
+      # @return Result - the Result of the dry run. See Result.
+      #
+      def self.these_commands(commands)
+        current_event_store = Sequent.configuration.event_store
+        current_event_publisher = Sequent.configuration.event_publisher
+        result = Result.new
+
+        Sequent.configuration.event_store = EventStoreProxy.new(result)
+        Sequent.configuration.event_publisher = RecordingEventPublisher.new(result)
+
+        Sequent.command_service.execute_commands(*commands)
+
+        result
+      ensure
+        Sequent.configuration.event_store = current_event_store
+        Sequent.configuration.event_publisher = current_event_publisher
+      end
+    end
+  end
+end

data/lib/sequent/util/util.rb

@@ -1,3 +1,4 @@
 require_relative 'skip_if_already_processing'
 require_relative 'timer'
 require_relative 'printer'
+require_relative 'dry_run'

data/lib/version.rb

@@ -1,3 +1,3 @@
 module Sequent
-  VERSION = '3.4.0'
+  VERSION = '3.5.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sequent
 version: !ruby/object:Gem::Version
-  version: 3.4.0
+  version: 3.5.0
 platform: ruby
 authors:
 - Lars Vonk
@@ -12,7 +12,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-12-09 00:00:00.000000000 Z
+date: 2020-02-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -152,6 +152,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 2.6.5
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -366,6 +380,7 @@ files:
 - lib/sequent/test/event_handler_helpers.rb
 - lib/sequent/test/event_stream_helpers.rb
 - lib/sequent/test/time_comparison.rb
+- lib/sequent/util/dry_run.rb
 - lib/sequent/util/printer.rb
 - lib/sequent/util/skip_if_already_processing.rb
 - lib/sequent/util/timer.rb