sequent 3.2.2 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10b5839af491a1fc854e512051185f6141b6bff465d4aea09fe7c6f20940ba4e
-  data.tar.gz: 32bccd0cc5b44a760e544a48b3be9578abcc9f9de7fbd083ca9ed6f38c5e5932
+  metadata.gz: 3322a4b950e847a5818555b2718df70e2b81a8e398074309a0b58c2a8d332ce5
+  data.tar.gz: 6136697a8a9596e999fabf3814509428b06188a0ac577fa3443a80ec190cbdd7
 SHA512:
-  metadata.gz: 6c45431a49ad4100a7ad0ebe812aecb75144a9bf847823268a98b85c96689948e83fcfa76fd1d0c66dea5dabe923d41ab820ceefeb07cf2605d2b98296ebe7d6
-  data.tar.gz: 3198cc99cf9bfa8ba955aecc4fd85fd7559f848a83c64c77d7a7092fafeb7c2aadfec4e31f587c929304537e306e2f5cebfcbbd780c14700c9b384daeaede68e
+  metadata.gz: f8ce675ae0a16274630066192086fb8c46bb0306e9280fd4b8901500af4a7af56844c5d6c40cd0f45a87342c33a4faeb2eee48f0dc0fb05a0a09046a2dea7414
+  data.tar.gz: e750e54d72de1c8641a513839c675adeb32fbeaa3435528a8aca755a951a7572d696e9348b7594e104f044978a0e9780f8e080ff1ad5e4ea9b7cc203fac6fee2

data/lib/notices.rb

@@ -0,0 +1,4 @@
+# This file is for any notices such as deprecation warnings, which should appear
+# in the logs during app boot. Adding such warnings in other places causes
+# lots of noise with duplicated messages, whereas this file is only
+# run once.

data/lib/sequent.rb

@@ -1,4 +1,7 @@
+require_relative 'sequent/application_record'
 require_relative 'sequent/sequent'
 require_relative 'sequent/core/core'
 require_relative 'sequent/util/util'
 require_relative 'sequent/migrations/migrations'
+
+require_relative 'notices'

data/lib/sequent/application_record.rb

@@ -0,0 +1,7 @@
+require 'active_record'
+
+module Sequent
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/lib/sequent/configuration.rb

@@ -13,6 +13,7 @@ module Sequent
 
     DEFAULT_MIGRATION_SQL_FILES_DIRECTORY = 'db/tables'
     DEFAULT_DATABASE_CONFIG_DIRECTORY = 'db'
+    DEFAULT_DATABASE_SCHEMA_DIRECTORY = 'db'
 
     DEFAULT_VIEW_SCHEMA_NAME = 'view_schema'
     DEFAULT_EVENT_STORE_SCHEMA_NAME= 'sequent_schema'
@@ -26,6 +27,10 @@ module Sequent
 
     DEFAULT_EVENT_RECORD_HOOKS_CLASS = Sequent::Core::EventRecordHooks
 
+    DEFAULT_STRICT_CHECK_ATTRIBUTES_ON_APPLY_EVENTS = false
+
+    DEFAULT_ERROR_LOCALE_RESOLVER = -> { I18n.locale || :en }
+
     attr_accessor :aggregate_repository
 
     attr_accessor :event_store,
@@ -49,14 +54,19 @@ module Sequent
 
     attr_accessor :logger
 
+    attr_accessor :error_locale_resolver
+
     attr_accessor :migration_sql_files_directory,
                   :view_schema_name,
                   :offline_replay_persistor_class,
                   :online_replay_persistor_class,
                   :number_of_replay_processes,
                   :database_config_directory,
+                  :database_schema_directory,
                   :event_store_schema_name
 
+    attr_accessor :strict_check_attributes_on_apply_events
+
     attr_reader :migrations_class_name,
                 :versions_table_name,
                 :replayed_ids_table_name
@@ -101,8 +111,11 @@ module Sequent
       self.offline_replay_persistor_class = DEFAULT_OFFLINE_REPLAY_PERSISTOR_CLASS
       self.online_replay_persistor_class = DEFAULT_ONLINE_REPLAY_PERSISTOR_CLASS
       self.database_config_directory = DEFAULT_DATABASE_CONFIG_DIRECTORY
+      self.database_schema_directory = DEFAULT_DATABASE_SCHEMA_DIRECTORY
+      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

@@ -100,11 +100,17 @@ module Sequent
       ##
       # Returns whether the event store has an aggregate with the given id
       def contains_aggregate?(aggregate_id)
-        Sequent.configuration.event_store.stream_exists?(aggregate_id)
+        Sequent.configuration.event_store.stream_exists?(aggregate_id) &&
+          Sequent.configuration.event_store.events_exists?(aggregate_id)
       end
 
       # 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_record.rb

@@ -32,7 +32,7 @@ module Sequent
     end
 
     # For storing Sequent::Core::Command in the database using active_record
-    class CommandRecord < ActiveRecord::Base
+    class CommandRecord < Sequent::ApplicationRecord
       include SerializesCommand
 
       self.table_name = "command_records"
@@ -42,7 +42,10 @@ module Sequent
       validates_presence_of :command_type, :command_json
 
       def parent
-        EventRecord.find_by(aggregate_id: event_aggregate_id, sequence_number: event_sequence_number)
+        EventRecord
+          .where(aggregate_id: event_aggregate_id, sequence_number: event_sequence_number)
+          .where('event_type != ?', Sequent::Core::SnapshotEvent.name)
+          .first
       end
 
       def children

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
 
@@ -45,6 +52,7 @@ module Sequent
               while(!command_queue.empty?) do
                 process_command(command_queue.pop)
               end
+              Sequent::Util.done_processing(:command_service_process_commands)
             end
           ensure
             command_queue.clear
@@ -54,9 +62,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)
@@ -89,6 +104,7 @@ module Sequent
 
     # Raised when BaseCommand.valid? returns false
     class CommandNotValid < ArgumentError
+      attr_reader :command
 
       def initialize(command)
         @command = 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_record.rb

@@ -1,5 +1,6 @@
 require 'active_record'
 require_relative 'sequent_oj'
+require_relative '../application_record.rb'
 
 module Sequent
   module Core
@@ -72,7 +73,7 @@ module Sequent
       end
     end
 
-    class EventRecord < ActiveRecord::Base
+    class EventRecord < Sequent::ApplicationRecord
       include SerializesEvent
 
       self.table_name = "event_records"

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
@@ -80,6 +88,9 @@ ORDER BY sequence_number ASC, (CASE event_type WHEN #{quote Sequent.configuratio
         Sequent.configuration.stream_record_class.exists?(aggregate_id: aggregate_id)
       end
 
+      def events_exists?(aggregate_id)
+        Sequent.configuration.event_record_class.exists?(aggregate_id: aggregate_id)
+      end
       ##
       # Replays all events in the event store to the registered event_handlers.
       #
@@ -158,7 +169,15 @@ SELECT aggregate_id
       private
 
       def column_names
-        @column_names ||= Sequent.configuration.event_record_class.column_names.reject { |c| c == 'id' }
+        @column_names ||= Sequent
+                            .configuration
+                            .event_record_class
+                            .column_names
+                            .reject { |c| c == primary_key_event_records }
+      end
+
+      def primary_key_event_records
+        @primary_key_event_records ||= Sequent.configuration.event_record_class.primary_key
       end
 
       def deserialize_event(event_hash)
@@ -200,7 +219,7 @@ SELECT aggregate_id
                    .join(',')
         columns = column_names.map { |c| connection.quote_column_name(c) }.join(',')
         sql = %Q{insert into #{connection.quote_table_name(Sequent.configuration.event_record_class.table_name)} (#{columns}) values #{values}}
-        Sequent.configuration.event_record_class.connection.insert(sql)
+        Sequent.configuration.event_record_class.connection.insert(sql, nil, primary_key_event_records)
       rescue ActiveRecord::RecordNotUnique
         fail OptimisticLockingError.new
       end

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

@@ -9,17 +9,33 @@ 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
+
         # module containing class methods to be added
         module ClassMethods
 
@@ -60,6 +76,7 @@ module Sequent
             class_eval <<EOS
               def update_all_attributes(attrs)
                 super if defined?(super)
+                ensure_known_attributes(attrs)
                 #{@types.map { |attribute, _|
               "@#{attribute} = attrs[:#{attribute}]"
             }.join("\n            ")}
@@ -157,9 +174,13 @@ EOS
           prefix ? HashWithIndifferentAccess[result.map { |k, v| ["#{prefix}_#{k}", v] }] : result
         end
 
-      end
-
+        def ensure_known_attributes(attrs)
+          return unless Sequent.configuration.strict_check_attributes_on_apply_events
 
+          unknowns = attrs.keys.map(&:to_s) - self.class.types.keys.map(&:to_s)
+          raise UnknownAttributeError.new("#{self.class.name} does not specify attrs: #{unknowns.join(", ")}") if unknowns.any?
+        end
+      end
     end
   end
 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/core/persistors/active_record_persistor.rb

@@ -104,7 +104,7 @@ module Sequent
         end
 
         def execute_sql(statement)
-          ActiveRecord::Base.connection.execute(statement)
+          Sequent::ApplicationRecord.connection.execute(statement)
         end
 
         def commit

data/lib/sequent/core/persistors/replay_optimized_postgres_persistor.rb

@@ -307,7 +307,7 @@ module Sequent
               end
 
               buf = ''
-              conn = ActiveRecord::Base.connection.raw_connection
+              conn = Sequent::ApplicationRecord.connection.raw_connection
               copy_data = StringIO.new csv.string
               conn.transaction do
                 conn.copy_data("COPY #{clazz.table_name} (#{column_names.join(",")}) FROM STDIN WITH csv") do
@@ -346,7 +346,7 @@ module Sequent
         private
 
         def cast_value_to_column_type(clazz, column_name, record)
-          ActiveRecord::Base.connection.type_cast(record[column_name.to_sym], @column_cache[clazz.name][column_name])
+          Sequent::ApplicationRecord.connection.type_cast(record[column_name.to_sym], @column_cache[clazz.name][column_name])
         end
       end
     end

data/lib/sequent/core/projector.rb

@@ -11,7 +11,26 @@ module Sequent
         end
 
         def managed_tables
-          @managed_tables
+          @managed_tables || managed_tables_from_superclass
+        end
+
+        def manages_no_tables
+          @manages_no_tables = true
+          manages_tables *[]
+        end
+
+        def manages_no_tables?
+          !!@manages_no_tables || manages_no_tables_from_superclass?
+        end
+
+        private
+
+        def managed_tables_from_superclass
+          self.superclass.managed_tables if self.superclass.respond_to?(:managed_tables)
+        end
+
+        def manages_no_tables_from_superclass?
+          self.superclass.manages_no_tables? if self.superclass.respond_to?(:manages_no_tables?)
         end
       end
 
@@ -96,7 +115,10 @@ module Sequent
         :commit
 
       private
+
       def ensure_valid!
+        return if self.class.manages_no_tables?
+
         fail "A Projector must manage at least one table. Did you forget to add `managed_tables` to #{self.class.name}?" if self.class.managed_tables.nil? || self.class.managed_tables.empty?
       end
     end