eventsimple 1.0.0

data/lib/eventsimple/event.rb

@@ -0,0 +1,189 @@
+module Eventsimple
+  module Event
+    require 'globalid'
+    include GlobalID::Identification
+
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    def drives_events_for(aggregate_klass, aggregate_id:, events_namespace: nil)
+      class_attribute :_events_namespace
+      self._events_namespace = events_namespace
+
+      class_attribute :_aggregate_klass
+      self._aggregate_klass = aggregate_klass
+
+      class_attribute :_aggregate_id
+      self._aggregate_id = aggregate_id
+
+      class_attribute :_outbox_mode
+      class_attribute :_outbox_concurrency
+
+      class_attribute :_on_invalid_transition
+      self._on_invalid_transition = ->(error) { raise error }
+
+      self.inheritance_column = :type
+      self.store_full_sti_class = false
+
+      attribute :metadata, MetadataType.new
+      attr_writer :skip_dispatcher
+      attr_writer :skip_apply_check
+
+      belongs_to _aggregate_klass.model_name.element.to_sym,
+        foreign_key: :aggregate_id,
+        primary_key: _aggregate_id,
+        class_name: _aggregate_klass.name.to_s,
+        inverse_of: :events,
+        autosave: false,
+        validate: false
+
+      default_scope { order('created_at ASC') }
+
+      before_validation :extend_validation
+      after_validation :perform_transition_checks
+      before_create :apply_and_persist
+      after_create :dispatch
+
+      include InstanceMethods
+      extend ClassMethods
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+    module InstanceMethods
+      def skip_dispatcher
+        @skip_dispatcher || false
+      end
+
+      def skip_apply_check
+        @skip_apply_check || false
+      end
+
+      # Apply the event to the aggregate passed in. The default behaviour is a no-op
+      def apply(aggregate); end
+
+      def can_apply?(_aggregate)
+        true
+      end
+
+      def apply_timestamps(aggregate)
+        aggregate.created_at ||= created_at
+        aggregate.updated_at = created_at
+      end
+
+      def perform_transition_checks
+        return if skip_apply_check
+        return if can_apply?(aggregate)
+
+        _on_invalid_transition.call(
+          Eventsimple::InvalidTransition.new(self.class),
+        )
+
+        raise ActiveRecord::Rollback
+      end
+
+      def extend_validation
+        validate_form = self.class.instance_variable_get(:@validate_with)
+        self.aggregate = aggregate.extend(validate_form) if validate_form
+      end
+
+      # Apply the transformation to the aggregate and save it.
+      def apply_and_persist
+        apply(aggregate)
+        apply_timestamps(aggregate)
+
+        # Persist!
+        aggregate.save!
+
+        self.aggregate = aggregate
+      end
+
+      def dispatch
+        EventDispatcher.dispatch(self) unless skip_dispatcher
+      end
+
+      def aggregate
+        public_send(_aggregate_klass.model_name.element)
+      end
+
+      def aggregate=(aggregate)
+        public_send("#{_aggregate_klass.model_name.element}=", aggregate)
+      end
+    end
+
+    module ClassMethods
+      def validate_with(form_klass)
+        @validate_with = form_klass
+      end
+
+      def rescue_invalid_transition(&block)
+        self._on_invalid_transition = block || ->(error) {}
+      end
+
+      # We don't store the full namespaced class name in the events table.
+      # Events for an entity are expected to be namespaced under _events_namespace.
+      def find_sti_class(type_name)
+        if _events_namespace.blank?
+          super(type_name)
+        else
+          super("#{_events_namespace}::#{type_name}")
+        end
+      end
+
+      # Use a no-op deleted class for events that no longer exist in the codebase
+      def sti_class_for(type_name)
+        super
+      rescue ActiveRecord::SubclassNotFound
+        klass_name = "Deleted__#{type_name.demodulize}"
+        return const_get(klass_name) if const_defined?(klass_name)
+
+        # NOTE: this should still update the timestamps for the model to prevent
+        #       projection drift (since the original projection will
+        #       have the timestamps applied for the deleted event).
+        klass = Class.new(self)
+
+        const_set(klass_name, klass)
+      end
+
+      # We want to automatically retry writes on concurrency failures. However events with sync
+      # reactors may have multiple nested events that are written within the same transaction.
+      # We can only catch and retry writes when they the outermost event encapsulating the whole
+      # transaction.
+      def create(*args, &block)
+        with_locks do
+          with_retries(args) { super }
+        end
+      end
+
+      def create!(*args, &block)
+        with_locks do
+          with_retries(args) { super }
+        end
+      end
+
+      def with_locks(&block)
+        if _outbox_mode
+          base_class.with_advisory_lock(base_class.name, { transaction: true }, &block)
+        else
+          yield
+        end
+      end
+
+      def with_retries(args, &block) # rubocop:disable Metrics/AbcSize
+        entity = args[0][_aggregate_klass.model_name.element.to_sym]
+
+        # Only implement retries when the event is not already inside a transaction.
+        if entity&.persisted? && !existing_transaction_in_progress?
+          Retriable.with_context(:optimistic_locking, on_retry: proc { entity.reload }, &block)
+        else
+          yield
+        end
+      rescue ActiveRecord::StaleObjectError => e
+        raise e unless existing_transaction_in_progress?
+
+        raise e, "#{e.message} No retries are attempted when already inside a transaction."
+      end
+
+      def existing_transaction_in_progress?
+        ActiveRecord::Base.connection.transaction_open?
+      end
+    end
+  end
+end

data/lib/eventsimple/event_dispatcher.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2017 Kickstarter, PBC
+
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+# Dispatcher implementation.
+module Eventsimple
+  class EventDispatcher
+    # Dispatches events to matching Reactors once.
+    # Called by all events after they are created.
+    def self.dispatch(event)
+      reactors = rules.for(event)
+      reactors.sync.each do |reactor|
+        reactor.new(event).call
+        event.reload
+      end
+      reactors.async.each do |reactor|
+        ReactorWorker.perform_async(event.to_global_id.to_s, reactor.to_s)
+      end
+    end
+
+    def self.rules
+      @rules ||= RuleSet.new
+    end
+
+    class RuleSet
+      def initialize
+        @rules = Hash.new { |h, k| h[k] = ReactorSet.new }
+      end
+
+      # Register events with their sync and async Reactors
+      def register(events:, sync:, async:)
+        events.each do |event|
+          @rules[event].add_sync sync
+          @rules[event].add_async async
+        end
+      end
+
+      # Return a ReactorSet containing all Reactors matching an Event
+      def for(event)
+        reactors = ReactorSet.new
+
+        @rules.each do |event_class, rule|
+          # Match event by class including ancestors. e.g. All events match a role for BaseEvent.
+          if event.is_a?(event_class)
+            reactors.add_sync rule.sync
+            reactors.add_async rule.async
+          end
+        end
+
+        reactors
+      end
+    end
+
+    # Contains sync and async reactors. Used to:
+    # * store reactors via Rules#register
+    # * return a set of matching reactors with Rules#for
+    class ReactorSet
+      attr_reader :sync, :async
+
+      def initialize
+        @sync = Set.new
+        @async = Set.new
+      end
+
+      def add_sync(reactors)
+        @sync += reactors
+      end
+
+      def add_async(reactors)
+        @async += reactors
+      end
+    end
+  end
+end

data/lib/eventsimple/generators/install_generator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Eventsimple
+  module Generators
+    class EventGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      desc "Generate Outbox Table Migration"
+      source_root File.expand_path("templates", __dir__)
+
+      argument :model_name, type: :string
+
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      def copy_migrations
+        migration_template "create_events.erb",
+          "db/migrate/create_#{model_name.underscore}_events.rb",
+          migration_version: migration_version
+
+        template "event.erb",
+          "app/models/#{model_name.underscore}_event.rb"
+
+        line = "class #{model_name.camelize} < ApplicationRecord"
+        gsub_file "app/models/#{model_name.underscore}.rb", /(#{Regexp.escape(line)})/mi do |match|
+          <<~RUBY
+            #{match}\n  extend Eventsimple::Entity
+              event_driven_by #{model_name.camelize}Event, aggregate_id: :id
+          RUBY
+        end
+      end
+
+      def migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/eventsimple/generators/outbox/install_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Eventsimple
+  module Generators
+    module Outbox
+      class InstallGenerator < Rails::Generators::Base
+        include Rails::Generators::Migration
+
+        desc "Generate Outbox Table Migration"
+        source_root File.expand_path("templates", __dir__)
+
+        def self.next_migration_number(dirname)
+          next_migration_number = current_migration_number(dirname) + 1
+          ActiveRecord::Migration.next_migration_number(next_migration_number)
+        end
+
+        def copy_migrations
+          migration_template "create_outbox_cursor.erb",
+            "db/migrate/create_eventsimple_outbox_cursor.rb",
+            migration_version: migration_version
+        end
+
+        def migration_version
+          "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+        end
+      end
+    end
+  end
+end

data/lib/eventsimple/generators/outbox/templates/create_outbox_cursor.erb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class CreateEventsimpleOutboxCursor < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :eventsimple_outbox_cursors do |t|
+      t.string :event_klass, null: false
+      t.integer :group_number, null: false
+      t.bigint :cursor, null: false
+
+      t.index [:event_klass, :group_number], unique: true
+    end
+  end
+end

data/lib/eventsimple/generators/templates/create_events.erb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class Create<%= model_name.camelize %>Events < ActiveRecord::Migration[7.0]
+  def change
+    create_table :<%= model_name.underscore %>_events do |t|
+      # Change this to string if your aggregates primary key is a string type
+      t.bigint :aggregate_id, null: false, index: true
+      t.string :idempotency_key, null: true
+      t.string :type, null: false
+      t.json :data, null: false, default: {}
+      t.json :metadata, null: false, default: {}
+
+      t.timestamps
+
+      t.index :idempotency_key, unique: true
+    end
+
+    # Enables optimistic locking on the evented table
+    add_column :<%= model_name.underscore.pluralize %>, :lock_version, :integer
+  end
+end

data/lib/eventsimple/generators/templates/event.erb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class <%= model_name.camelize %>Event < ApplicationRecord
+  extend Eventsimple::Event
+  drives_events_for <%= model_name.camelize %>,
+    aggregate_id: :id,
+    events_namespace: '<%= model_name.camelize %>Component::Events'
+end

data/lib/eventsimple/invalid_transition.rb

@@ -0,0 +1,14 @@
+module Eventsimple
+  class InvalidTransition < StandardError
+    attr_reader :klass
+
+    def initialize(klass = nil)
+      @klass = klass
+      super
+    end
+
+    def to_s
+      "Invalid State Transition for #{klass}"
+    end
+  end
+end

data/lib/eventsimple/message.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Eventsimple
+  class Message < Dry::Struct
+    transform_keys(&:to_sym)
+
+    # dry types will apply default values only on missing keys
+    # modify the behaviour so the default is used even when the key is present but nil
+    transform_types do |type|
+      if type.default?
+        type.constructor do |value|
+          value.nil? ? Dry::Types::Undefined : value
+        end
+      else
+        type
+      end
+    end
+
+    def inspect
+      as_json
+    end
+  end
+end

data/lib/eventsimple/metadata.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Event metadata store information on the event, for example the user who triggered the event.
+module Eventsimple
+  class Metadata < Eventsimple::Message
+    schema schema.strict
+
+    attribute? :actor_id, DryTypes::Strict::String
+    attribute? :reason, DryTypes::Strict::String
+  end
+end

data/lib/eventsimple/metadata_type.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Eventsimple
+  class MetadataType < ActiveModel::Type::Value
+    def type
+      :metadata_type
+    end
+
+    def cast_value(value)
+      case value
+      when String
+        decoded = ActiveSupport::JSON.decode(value)
+        return decoded if decoded.empty?
+
+        Eventsimple.configuration.metadata_klass.new(decoded)
+      when Hash
+        Eventsimple.configuration.metadata_klass.new(value)
+      when Eventsimple.configuration.metadata_klass
+        value
+      end
+    end
+
+    def serialize(value)
+      case value
+      when Hash, Eventsimple.configuration.metadata_klass
+        ActiveSupport::JSON.encode(value)
+      else
+        super
+      end
+    end
+
+    def deserialize(value)
+      decoded = ActiveSupport::JSON.decode(value)
+
+      Eventsimple.configuration.metadata_klass.new(decoded)
+    end
+  end
+end

data/lib/eventsimple/outbox/consumer.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'eventsimple/outbox/models/cursor'
+
+module Eventsimple
+  module Outbox
+    module Consumer
+      def self.extended(klass)
+        klass.class_exec do
+          class_attribute :_event_klass
+          class_attribute :_processor_klass
+          class_attribute :stop_consumer, default: false
+
+          Signal.trap('SIGINT') do
+            self.stop_consumer = true
+            STDOUT.puts('SIGINT received, stopping consumer')
+          end
+        end
+      end
+
+      def consumes_event(event_klass, concurrency: 1)
+        event_klass._outbox_mode = true
+        event_klass._outbox_concurrency = concurrency
+
+        self._event_klass = event_klass
+      end
+
+      def processor(processor_klass)
+        self._processor_klass = processor_klass
+      end
+
+      def start # rubocop:disable Metrics/AbcSize
+        cursor = Outbox::Cursor.fetch(_event_klass, 0)
+
+        until stop_consumer
+          _event_klass.unscoped.in_batches(start: cursor + 1, load: true).each do |batch|
+            batch.each do |event|
+              _processor_klass.new(event).call
+
+              break if stop_consumer
+            end
+
+            cursor = batch.last.id
+            Outbox::Cursor.set(_event_klass, 0, cursor)
+          end
+
+          sleep(1)
+        end
+      end
+    end
+  end
+end

data/lib/eventsimple/outbox/models/cursor.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Eventsimple
+  module Outbox
+    class Cursor < ApplicationRecord
+      self.table_name = 'eventsimple_outbox_cursors'
+
+      def self.fetch(event_klass, group_number)
+        existing = find_by(event_klass: event_klass.to_s, group_number: group_number)
+        existing ? existing.cursor : 0
+      end
+
+      def self.set(event_klass, group_number, cursor)
+        upsert(
+          {
+            event_klass: event_klass.to_s,
+            group_number: group_number,
+            cursor: cursor,
+          },
+          unique_by: [:event_klass, :group_number],
+        )
+      end
+    end
+  end
+end

data/lib/eventsimple/reactor_worker.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Eventsimple
+  class ReactorWorker
+    include Sidekiq::Worker
+
+    def perform(event_global_id, reactor_class)
+      event = Retriable.with_context(:reactor) do
+        ApplicationRecord.uncached { GlobalID::Locator.locate event_global_id }
+      end
+    rescue ActiveRecord::RecordNotFound
+      Rails.logger.error("Event #{event_global_id} not found for reactor: #{reactor_class}")
+    else
+      reactor = reactor_class.constantize
+      reactor.new(event).call
+    end
+  end
+end

data/lib/eventsimple/support/spec_helpers.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+RSpec.shared_examples 'an event which synchronously dispatches' do |dispatcher_klass|
+  specify do
+    reactors = Eventsimple::EventDispatcher.rules.for(described_class.new)
+
+    expect(reactors.sync).to include(dispatcher_klass)
+  end
+end
+
+RSpec.shared_examples 'an event which asynchronously dispatches' do |dispatcher_klass|
+  specify do
+    reactors = Eventsimple::EventDispatcher.rules.for(described_class.new)
+
+    expect(reactors.async).to include(dispatcher_klass)
+  end
+end
+
+RSpec.shared_examples 'an event in invalid state' do
+  it 'raises an InvalidTransition error' do
+    expect { event.save }.to raise_error(Eventsimple::InvalidTransition).and not_change(
+      event.class, :count
+    )
+  end
+end
+
+RSpec.shared_examples 'an event in invalid state that is rescued' do
+  context 'when save' do
+    it 'does not InvalidTransition error on save' do
+      expect { event.save }.not_to raise_error
+    end
+
+    it 'does not write event on save' do
+      expect { event.save }.not_to change(event.class, :count)
+    end
+  end
+
+  context 'when save!' do
+    it 'does not InvalidTransition error on save!' do
+      expect { event.save! }.not_to raise_error
+    end
+
+    it 'does not write event on save!' do
+      expect { event.save! }.not_to change(event.class, :count)
+    end
+  end
+end

data/lib/eventsimple/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Eventsimple
+  VERSION = '1.0.0'
+end

data/lib/eventsimple.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "eventsimple/version"
+require "eventsimple/engine"
+
+require 'active_model'
+require 'active_support'
+require 'dry-types'
+require 'dry-struct'
+require 'retriable'
+require 'sidekiq'
+
+require 'dry_types'
+
+require 'eventsimple/configuration'
+require 'eventsimple/message'
+require 'eventsimple/data_type'
+require 'eventsimple/metadata_type'
+require 'eventsimple/metadata'
+require 'eventsimple/dispatcher'
+require 'eventsimple/event_dispatcher'
+require 'eventsimple/reactor_worker'
+require 'eventsimple/invalid_transition'
+
+require 'eventsimple/entity'
+require 'eventsimple/event'
+
+require 'eventsimple/generators/install_generator'
+require 'eventsimple/generators/outbox/install_generator'
+
+module Eventsimple
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end