sequent 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ae011c7edda7f721ed6973ee7dc7d34a1bd4bef1
-  data.tar.gz: 29349622be7751d7d371ad9c56232aaa880e7aa1
+  metadata.gz: ffdbe1d8e772c148815f98b0d7baa96f32dd5870
+  data.tar.gz: 3b7ed01b18a23c5d7b8522a4b5d0c1af311be02f
 SHA512:
-  metadata.gz: 5b832a64d8daaaf0008426f7acd40489934ff95ec666feac04751602305cf404d0b6f2b6a2dc0c89aa504de1bc5bcc468788d22f3f1f3a57240e99658fc01bfb
-  data.tar.gz: 77e7beb17a0e7341d0cff134c03a6428ceec7fcb64266cf230058c493a37fe766713a2bd23bdf20095eeb14a90ede3cc2c0abfa5a49502e7f149bf213d8f7b04
+  metadata.gz: 5ec2840094aa3f915222047623d3f570563efa800736883c9d07b724773b0948b74602d26560337bb20455fde183a066181cbe594959ca52ebd1d73fea6a0f9e
+  data.tar.gz: 60ac65d32eda16ce7db21cb51ba0a61b6b741b86636185569b1683c76a983c35d6ca806a744befdd195df997ecb3b8df481fd17a15e312d648a7fa816d3127a7

data/lib/sequent/core/aggregate_repository.rb

@@ -0,0 +1,94 @@
+module Sequent
+  module Core
+    # Repository for aggregates.
+    #
+    # Implements the Unit-Of-Work and Identity-Map patterns
+    # to ensure each aggregate is only loaded once per transaction
+    # and that you always get the same aggregate instance back.
+    #
+    # On commit all aggregates associated with the Unit-Of-Work are
+    # queried for uncommitted events. After persisting these events
+    # the uncommitted events are cleared from the aggregate.
+    #
+    # The repository is keeps track of the Unit-Of-Work per thread,
+    # so can be shared between threads.
+    class AggregateRepository
+      # Key used in thread local
+      AGGREGATES_KEY = 'Sequent::Core::AggregateRepository::aggregates'.to_sym
+
+      class NonUniqueAggregateId < Exception
+        def initialize(existing, new)
+          super "Duplicate aggregate #{new} with same key as existing #{existing}"
+        end
+      end
+
+      def initialize(event_store)
+        @event_store = event_store
+        clear
+      end
+
+      # Adds the given aggregate to the repository (or unit of work).
+      #
+      # Only when +commit+ is called all aggregates in the unit of work are 'processed'
+      # and all uncammited_events are stored in the +event_store+
+      #
+      def add_aggregate(aggregate)
+        if aggregates.has_key?(aggregate.id)
+          raise NonUniqueAggregateId.new(aggregate, aggregates[aggregate.id]) unless aggregates[aggregate.id].equal?(aggregate)
+        else
+          aggregates[aggregate.id] = aggregate
+        end
+      end
+
+      # Throws exception if not exists.
+      def ensure_exists(aggregate_id, clazz)
+        !load_aggregate(aggregate_id, clazz).nil?
+      end
+
+      # Loads aggregate by given id and class
+      # Returns the one in the current Unit Of Work otherwise loads it from history.
+      #
+      # If we implement snapshotting this is the place.
+      def load_aggregate(aggregate_id, clazz)
+        if aggregates.has_key?(aggregate_id)
+          result = aggregates[aggregate_id]
+          raise TypeError, "#{result.class} is not a #{clazz}" unless result.is_a?(clazz)
+          result
+        else
+          events = @event_store.load_events(aggregate_id)
+          aggregates[aggregate_id] = clazz.load_from_history(events)
+        end
+      end
+
+      # Gets all uncommitted_events from the 'registered' aggregates
+      # and stores them in the event store.
+      # The command is 'attached' for traceability purpose so we can see
+      # which command resulted in which events.
+      #
+      # This is all abstracted away if you use the Sequent::Core::CommandService
+      #
+      def commit(command)
+        all_events = []
+        aggregates.each_value { |aggregate| all_events += aggregate.uncommitted_events }
+        return if all_events.empty?
+        aggregates.each_value { |aggregate| aggregate.clear_events }
+        store_events command, all_events
+      end
+
+      # Clears the Unit of Work.
+      def clear
+        Thread.current[AGGREGATES_KEY] = {}
+      end
+
+      private
+
+      def aggregates
+        Thread.current[AGGREGATES_KEY]
+      end
+
+      def store_events(command, events)
+        @event_store.commit_events(command, events)
+      end
+    end
+  end
+end

data/lib/sequent/core/aggregate_root.rb

@@ -0,0 +1,87 @@
+require_relative 'helpers/self_applier'
+
+module Sequent
+  module Core
+    # Base class for all your domain classes.
+    #
+    # +load_from_history+ functionality to be loaded_from_history, meaning a stream of events.
+    #
+    class AggregateRoot
+      include Helpers::SelfApplier
+
+      attr_reader :id, :uncommitted_events, :sequence_number
+
+      def self.load_from_history(events)
+        aggregate_root = allocate() # allocate without calling new
+        aggregate_root.load_from_history(events)
+        aggregate_root
+      end
+
+      def initialize(id)
+        @id = id
+        @uncommitted_events = []
+        @sequence_number = 1
+      end
+
+      def load_from_history(events)
+        raise "Empty history" if events.empty?
+        @id = events.first.aggregate_id
+        @uncommitted_events = []
+        @sequence_number = events.size + 1
+        events.each { |event| handle_message(event) }
+      end
+
+      def to_s
+        "#{self.class.name}: #{@id}"
+      end
+
+
+      def clear_events
+        uncommitted_events.clear
+      end
+
+      protected
+
+      def build_event(event, params = {})
+        event.new({aggregate_id: @id, sequence_number: @sequence_number}.merge(params))
+      end
+
+      # Provide subclasses nice DSL to 'apply' events via:
+      #
+      #   def send_invoice
+      #     apply InvoiceSentEvent, send_date: DateTime.now
+      #   end
+      #
+      def apply(event, params={})
+        event = build_event(event, params) if event.is_a?(Class)
+        handle_message(event)
+        @uncommitted_events << event
+        @sequence_number += 1
+      end
+    end
+
+    # You can use this class when running in a multi tenant environment
+    # It basically makes sure that the +organization_id+ (the tenant_id for historic reasons)
+    # is available for the subclasses
+    class TenantAggregateRoot < AggregateRoot
+      attr_reader :organization_id
+
+      def initialize(id, organization_id)
+        super(id)
+        @organization_id = organization_id
+      end
+
+      def load_from_history(events)
+        raise "Empty history" if events.empty?
+        @organization_id = events.first.organization_id
+        super(events)
+      end
+
+      protected
+
+      def build_event(event, params = {})
+        super(event, {organization_id: @organization_id}.merge(params))
+      end
+    end
+  end
+end

data/lib/sequent/core/base_command_handler.rb

@@ -0,0 +1,39 @@
+require_relative 'helpers/self_applier'
+require_relative 'helpers/uuid_helper'
+
+module Sequent
+  module Core
+    # Base class for command handlers
+    # CommandHandlers are responsible for propagating a command to the correct Sequent::Core::AggregateRoot
+    # or creating a new one. For example:
+    #
+    #   class InvoiceCommandHandler < Sequent::Core::BaseCommandHandler
+    #     on CreateInvoiceCommand do |command|
+    #       repository.add_aggregate Invoice.new(command.aggregate_id)
+    #     end
+    #
+    #     on PayInvoiceCommanddo |command|
+    #       do_with_aggregate(command, Invoice) {|invoice|invoice.pay(command.pay_date)}
+    #     end
+    #   end
+    class BaseCommandHandler
+      include Sequent::Core::Helpers::SelfApplier,
+              Sequent::Core::Helpers::UuidHelper
+
+      def initialize(repository)
+        @repository = repository
+      end
+
+      protected
+      def do_with_aggregate(command, clazz, aggregate_id = nil)
+        aggregate = @repository.load_aggregate(aggregate_id.nil? ? command.aggregate_id : aggregate_id, clazz)
+        yield aggregate if block_given?
+      end
+
+      protected
+      def repository
+        @repository
+      end
+    end
+  end
+end

data/lib/sequent/core/base_event_handler.rb

@@ -0,0 +1,51 @@
+require_relative 'helpers/self_applier'
+
+module Sequent
+  module Core
+    # EventHandlers listen to events and handle them according to their responsibility.
+    #
+    # Examples:
+    # * Updating view states
+    # * Sending emails
+    # * Executing other commands based on events (chainging)
+    #
+    # Example of updating view state, in this case the InvoiceRecord table representing an Invoice
+    #
+    #   class InvoiceCommandHandler < Sequent::Core::BaseCommandHandler
+    #     on CreateInvoiceCommand do |command|
+    #       create_record(
+    #         InvoiceRecord,
+    #         recipient: command.recipient,
+    #         amount: command.amount
+    #       )
+    #     end
+    #   end
+    #
+    # Please note that the actual storage is abstracted away in the +record_session+. Reason
+    # is when replaying the entire event_store our default choice, active_record, is too slow.
+    # Also we want to give the opportunity to use other storage mechanisms for the view state.
+    # See the +def_delegators+ which method to implement.
+    # Due to this abstraction you can not traverse into child objects when using ActiveRecord
+    # like you are used to:
+    #
+    #   invoice_record.line_item_records << create_record(LineItemRecord, ...)
+    #
+    # In this case you should simply do:
+    #
+    #   create_record(LineItemRecord, invoice_id: invoice_record.aggregate_id)
+    #
+    class BaseEventHandler
+      extend Forwardable
+      include Helpers::SelfApplier
+
+      def initialize(record_session = Sequent::Core::RecordSessions::ActiveRecordSession.new)
+        @record_session = record_session
+      end
+
+      def_delegators :@record_session, :update_record, :create_record, :create_or_update_record, :get_record!, :get_record,
+                     :delete_all_records, :update_all_records, :do_with_records, :do_with_record, :delete_record,
+                     :find_records, :last_record
+
+    end
+  end
+end

data/lib/sequent/core/command.rb

@@ -0,0 +1,79 @@
+require_relative 'helpers/copyable'
+require_relative 'helpers/attribute_support'
+require_relative 'helpers/uuid_helper'
+require_relative 'helpers/equal_support'
+require_relative 'helpers/param_support'
+require_relative 'helpers/mergable'
+
+module Sequent
+  module Core
+    # Base command
+    class BaseCommand
+      include ActiveModel::Validations,
+              ActiveModel::Serializers::JSON,
+              Sequent::Core::Helpers::Copyable,
+              Sequent::Core::Helpers::AttributeSupport,
+              Sequent::Core::Helpers::UuidHelper,
+              Sequent::Core::Helpers::EqualSupport,
+              Sequent::Core::Helpers::ParamSupport,
+              Sequent::Core::Helpers::Mergable
+
+      attrs created_at: DateTime
+
+      self.include_root_in_json = false
+
+      def initialize(args = {})
+        update_all_attributes args
+        @created_at = DateTime.now
+      end
+
+    end
+
+    module UpdateSequenceNumber
+      extend ActiveSupport::Concern
+      included do
+        attrs sequence_number: Integer
+        validates_presence_of :sequence_number
+        validates_numericality_of :sequence_number, only_integer: true, allow_nil: true, allow_blank: true, greater_than: 0
+      end
+    end
+
+    # Most commonly used command
+    # Command can be instantiated just by using:
+    #
+    #   Command.new(aggregate_id: "1", user_id: "joe")
+    #
+    # But the Sequent::Core::Helpers::ParamSupport also enables Commands
+    # to be created from a params hash (like the one from Sinatra) as follows:
+    #
+    #   command = Command.from_params(params)
+    #
+    class Command < BaseCommand
+      attrs aggregate_id: String, user_id: String
+
+      def initialize(args = {})
+        raise ArgumentError, "Missing aggregate_id" if args[:aggregate_id].nil?
+        super
+      end
+
+    end
+
+    class UpdateCommand < Command
+      include UpdateSequenceNumber
+    end
+
+    class TenantCommand < Command
+      attrs organization_id: String
+
+      def initialize(args = {})
+        raise ArgumentError, "Missing organization_id" if args[:organization_id].nil?
+        super
+      end
+    end
+
+    class UpdateTenantCommand < TenantCommand
+      include UpdateSequenceNumber
+    end
+
+  end
+end

data/lib/sequent/core/command_record.rb

@@ -0,0 +1,26 @@
+require 'active_record'
+module Sequent
+  module Core
+    # For storing Sequent::Core::Command in the database using active_record
+    class CommandRecord < ActiveRecord::Base
+
+      self.table_name = "command_records"
+
+      validates_presence_of :command_type, :command_json
+
+      def command
+        args = JSON.parse(command_json)
+        Class.const_get(command_type.to_sym).deserialize_from_json(args)
+      end
+
+      def command=(command)
+        self.created_at = command.created_at
+        self.aggregate_id = command.aggregate_id if command.respond_to? :aggregate_id
+        self.organization_id = command.organization_id if command.respond_to? :organization_id
+        self.user_id = command.user_id if command.respond_to? :user_id
+        self.command_type = command.class.name
+        self.command_json = command.to_json.to_s
+      end
+    end
+  end
+end

data/lib/sequent/core/command_service.rb

@@ -0,0 +1,118 @@
+require_relative 'transactions/no_transactions'
+
+module Sequent
+  module Core
+
+    class CommandServiceConfiguration
+      attr_accessor :event_store,
+                    :command_handler_classes,
+                    :transaction_provider,
+                    :filters
+
+      def initialize
+        @command_handler_classes = []
+        @transaction_provider = Sequent::Core::Transactions::NoTransactions.new
+        @filters = []
+      end
+
+    end
+
+    #
+    # Single point in the application where subclasses of Sequent::Core::BaseCommand
+    # are executed. This will initiate the entire flow of:
+    #
+    # * 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
+    #
+    class CommandService
+
+      class << self
+        attr_accessor :configuration,
+                      :instance
+      end
+
+      # Creates a new CommandService and overwrites all existing config.
+      # The new CommandService can be retrieved via the +CommandService.instance+ method.
+      #
+      # If you don't want a singleton you can always instantiate it yourself using the +CommandService.new+.
+      def self.configure
+        self.configuration = CommandServiceConfiguration.new
+        yield(configuration) if block_given?
+        self.instance = CommandService.new(configuration)
+      end
+
+      # +DefaultCommandServiceConfiguration+ Configuration class for the CommandService containing:
+      #
+      #   +event_store+ The Sequent::Core::EventStore
+      #   +command_handler_classes+ Array of BaseCommandHandler classes that need to handle commands
+      #   +transaction_provider+ How to do transaction management. Defaults to Sequent::Core::Transactions::NoTransactions
+      #   +filters+ List of filter that respond_to :execute(command). Can be useful to do extra checks (security and such).
+      def initialize(configuration = CommandServiceConfiguration.new)
+        @event_store = configuration.event_store
+        @repository = AggregateRepository.new(configuration.event_store)
+        @filters = configuration.filters
+        @transaction_provider = configuration.transaction_provider
+        @command_handlers = configuration.command_handler_classes.map { |handler| handler.new(@repository) }
+      end
+
+      # Executes the given commands in a single transactional block as implemented by the +transaction_provider+
+      #
+      # For each command:
+      #
+      # * 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)
+        begin
+          @transaction_provider.transactional do
+            commands.each do |command|
+              @filters.each { |filter| filter.execute(command) }
+
+              if command.valid?
+                @command_handlers.each do |command_handler|
+                  command_handler.handle_message command if command_handler.handles_message? command
+                end
+              end
+
+              @repository.commit(command)
+              raise CommandNotValid.new(command) unless command.validation_errors.empty?
+            end
+          end
+        ensure
+          @repository.clear
+        end
+
+      end
+
+      def remove_event_handler(clazz)
+        @event_store.remove_event_handler(clazz)
+      end
+
+    end
+
+    # Raised when BaseCommand.valid? returns false
+    class CommandNotValid < ArgumentError
+
+      def initialize(command)
+        @command = command
+        msg = @command.respond_to?(:aggregate_id) ? " #{@command.aggregate_id}" : ""
+        super "Invalid command #{@command.class.to_s}#{msg}, errors: #{@command.validation_errors}"
+      end
+
+      def errors(prefix = nil)
+        @command.validation_errors(prefix)
+      end
+
+      def errors_with_command_prefix
+        errors(@command.class.to_s.underscore)
+      end
+    end
+
+  end
+end
+
+
+

data/lib/sequent/core/core.rb

@@ -0,0 +1,15 @@
+require_relative 'helpers/helpers'
+require_relative 'record_sessions/record_sessions'
+require_relative 'transactions/transactions'
+require_relative 'aggregate_repository'
+require_relative 'aggregate_root'
+require_relative 'base_command_handler'
+require_relative 'command'
+require_relative 'command_service'
+require_relative 'event'
+require_relative 'value_object'
+require_relative 'base_event_handler'
+require_relative 'event_store'
+require_relative 'tenant_event_store'
+require_relative 'event_record'
+require_relative 'command_record'

data/lib/sequent/core/event.rb

@@ -0,0 +1,62 @@
+require 'active_model'
+require_relative 'helpers/string_support'
+require_relative 'helpers/equal_support'
+require_relative 'helpers/attribute_support'
+require_relative 'helpers/copyable'
+
+module Sequent
+  module Core
+    class Event
+      include Sequent::Core::Helpers::StringSupport,
+              Sequent::Core::Helpers::EqualSupport,
+              Sequent::Core::Helpers::AttributeSupport,
+              Sequent::Core::Helpers::Copyable,
+              ActiveModel::Serializers::JSON
+      attrs aggregate_id: String, sequence_number: Integer, created_at: DateTime
+      self.include_root_in_json = false
+
+      def initialize(args = {})
+        update_all_attributes args
+        raise "Missing aggregate_id" unless @aggregate_id
+        raise "Missing sequence_number" unless @sequence_number
+        @created_at ||= DateTime.now
+      end
+
+      def payload
+        result = {}
+        instance_variables.reject { |k| payload_variables.include?(k.to_s) }.each do |k|
+          result[k.to_s[1 .. -1].to_sym] = instance_variable_get(k)
+        end
+        result
+      end
+      protected
+      def payload_variables
+        %w{@aggregate_id @sequence_number @created_at @underscored}
+      end
+
+    end
+
+    class TenantEvent < Event
+
+      attrs organization_id: String
+
+      def initialize(args = {})
+        super
+        raise "Missing organization_id" unless @organization_id
+      end
+
+      protected
+      def payload_variables
+        super << "@organization_id"
+      end
+
+    end
+
+    class CreateEvent < TenantEvent
+
+    end
+
+  end
+end
+
+

data/lib/sequent/core/event_record.rb

@@ -0,0 +1,34 @@
+require 'oj'
+require 'active_record'
+
+module Sequent
+  module Core
+    class EventRecord < ActiveRecord::Base
+
+      self.table_name = "event_records"
+
+      belongs_to :command_record
+
+      validates_presence_of :aggregate_id, :sequence_number, :event_type, :event_json
+      validates_numericality_of :sequence_number
+
+
+      def event
+        payload = Oj.strict_load(event_json)
+        Class.const_get(event_type.to_sym).deserialize_from_json(payload)
+      end
+
+      def event=(event)
+        self.aggregate_id = event.aggregate_id
+        self.sequence_number = event.sequence_number
+        self.organization_id = event.organization_id if event.respond_to?(:organization_id)
+        self.event_type = event.class.name
+        self.created_at = event.created_at
+        self.event_json = event.to_json.to_s
+      end
+
+    end
+
+  end
+end
+