rails-transactional-outbox 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6343854fdf11162d383989d784559a868d52eb17b5b2eb0ec00b52c7d91997c
-  data.tar.gz: 351f3beae606216af85b13f42a2262675c8de21fb2f77588c9ad0c249c4cc187
+  metadata.gz: 60bbddad0806646606ec74645b6cdeb9e4cb36775f661f9a5226822d12e9cd78
+  data.tar.gz: c7e9b82b9f3c84b9f09b8b27728a55562e524be4ce2e0f16653baeee965941f0
 SHA512:
-  metadata.gz: 43707b7e3083d3c8512c03e9db85601f10fa77664a180b87abd34ca5b641b51ffb2e3b4add3eea7129fd1adad480f667c0531a43fc783b4548f18792d32bd6a5
-  data.tar.gz: e8ac0f50cacfa30d0b8fab99299cdafec95fb5cf9d1451824957dd21a2cd7fc207b9fbc728ee2b4d5c2b63de287036558d39916bd7470eb6ae4ac10cef443ed7
+  metadata.gz: 3848c22971da6d9e727ae2a9430995ad225cbdd06df4fdcc7a6dcb93c98ec0fef7f1e9102ab9eec01d30889449d9ac9a6c33d87a5e239309ebb8bd2ec3366532
+  data.tar.gz: 4895905ed12adead29478d3d2b235625587c2ad43f65b6e87592a1b19010af2097dfd149c2567c9ef91fee4838e45aa353a0f7a0202bb977bbdbd5e7065d6574

data/.rubocop.yml

@@ -115,6 +115,7 @@ Metrics/AbcSize:
   Exclude:
     - 'lib/rails_transactional_outbox/runner.rb'
     - 'lib/rails_transactional_outbox/outbox_entries_processor.rb'
+    - 'lib/rails_transactional_outbox/outbox_entries_processors/non_ordered_processor.rb'
 
 Metrics/MethodLength:
   Max: 20
@@ -132,10 +133,12 @@ Lint/EmptyClass:
   Exclude:
     - 'lib/rails_transactional_outbox/error_handlers.rb'
     - 'lib/rails_transactional_outbox/record_processors.rb'
+    - 'lib/rails_transactional_outbox/outbox_entries_processors.rb'
 
 Metrics/BlockLength:
   Exclude:
     - 'lib/rails_transactional_outbox/reliable_model.rb'
+    - 'lib/rails_transactional_outbox/outbox_model.rb'
 
 Lint/ConstantDefinitionInBlock:
   Exclude:

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [0.2.0] - 2022-09-08
+
+- Introduce `RailsTransactionalOutbox::OutboxEntriesProcessors::OrderedByCausalityKeyProcessor` 
+
 ## [0.1.0] - 2022-08-23
 
 - Initial release

data/Gemfile

@@ -10,6 +10,7 @@ gem "rake", "~> 13.0"
 gem "crypt_keeper", github: "jmazzi/crypt_keeper"
 gem "ddtrace"
 gem "pg"
+gem "redlock"
 gem "rspec", "~> 3.0"
 gem "rubocop", require: false
 gem "rubocop-performance"

data/Gemfile.lock

@@ -9,7 +9,7 @@ GIT
 PATH
   remote: .
   specs:
-    rails-transactional-outbox (0.1.0)
+    rails-transactional-outbox (0.2.0)
       activerecord (>= 5)
       activesupport (>= 3.2)
       concurrent-ruby
@@ -73,6 +73,8 @@ GEM
     rainbow (3.1.1)
     rake (13.0.6)
     redis (4.8.0)
+    redlock (1.3.0)
+      redis (>= 3.0.0, < 6.0)
     regexp_parser (2.5.0)
     rexml (3.2.5)
     rspec (3.11.0)
@@ -130,6 +132,7 @@ DEPENDENCIES
   pg
   rails-transactional-outbox!
   rake (~> 13.0)
+  redlock
   rspec (~> 3.0)
   rubocop
   rubocop-performance

data/README.md

@@ -39,6 +39,11 @@ Rails.application.config.to_prepare do
     config.transactional_outbox_worker_idle_delay_multiplier = 5 # optional, defaults to 1, if there are no outbox entries to be processed, then the sleep time for the thread will be equal to transactional_outbox_worker_idle_delay_multiplier * transactional_outbox_worker_sleep_seconds  
     config.outbox_batch_size = 100 # optional, defaults to 100
     config.add_record_processor(MyCustomOperationProcerssor) # optional, by default it contains only one processor for ActiveRecord, but you could add more
+    
+    config.lock_client = Redlock::Client.new([ENV["REDIS_URL"]]) # required if you want to use RailsTransactionalOutbox::OutboxEntriesProcessors::OrderedByCausalityKeyProcessor, defaults to RailsTransactionalOutbox::NullLockClient. Check its interface and the interface of `redlock` gem. To cut the long story short, when the lock is acquired, a hash with the structure outlined in RailsTransactionalOutbox::NullLockClient should be yielded, if the lock is not acquired, a nil should be yielded.
+    config.lock_expiry_time  = 10_000 # not required, defaults to 10_000, the unit is milliseconds
+    config.outbox_entries_processor = `RailsTransactionalOutbox::OutboxEntriesProcessors::OrderedByCausalityKeyProcessor`.new # not required, defaults to RailsTransactionalOutbox::OutboxEntriesProcessors::NonOrderedProcessor.new
+    config.outbox_entry_causality_key_resolver = ->(model) { model.tenant_id } # not required, defaults to a lambda returning nil. Needed when using `outbox_entry_causality_key_resolver`  
   end
 end
 ```
@@ -66,6 +71,7 @@ create_table(:outbox_entries) do |t|
   t.datetime "processed_at"
   t.text "arguments", null: false, default: "{}"
   t.text "changeset", null: false, default: "{}"
+  t.string "causality_key"
   t.datetime "failed_at"
   t.datetime "retry_at"
   t.string "error_class"
@@ -79,6 +85,7 @@ create_table(:outbox_entries) do |t|
   t.index ["context"], name: "idx_outbox_enc_entries_on_topic"
   t.index ["created_at"], name: "idx_outbox_enc_entries_on_created_at"
   t.index ["created_at"], name: "idx_outbox_enc_entries_on_created_at_not_processed", where: "processed_at IS NULL"
+  t.index ["causality_key", created_at"], name: "idx_outbox_enc_entries_on_c_key_crtd_at_n_proc", where: "processed_at IS NULL"
   t.index %w[resource_class created_at], name: "idx_outbox_enc_entries_on_resource_class_and_created_at"
   t.index %w[resource_class processed_at], name: "idx_outbox_enc_entries_on_resource_class_and_processed_at"
 end
@@ -112,6 +119,19 @@ When executing the callbacks, you can use `previous_changes` which will contain
 
 Inclusion of this module will result in OutboxEntry records being created after create/update/destroy. For these entries, the `context` column will be populated with `active_record` value.
 
+### Ordering/Preserving causality
+
+There are two type of processors that have very different behavior depending on the concurrency:
+
+1. `RailsTransactionalOutbox::OutboxEntriesProcessors::NonOrderedProcessor` (used by default):
+
+By default, the order will be preserved only if there is no concurrency (i.e. a single process with a single thread). Internally, `.lock("FOR UPDATE SKIP LOCKED")` is used to avoid conflicts and other issues related to concurrency but at the cost of no longer preserving the causality of outbox entries (although the entries are ordered by `created_at`).
+
+2`RailsTransactionalOutbox::OutboxEntriesProcessors::OrderedByCausalityKeyProcessor`:
+
+Uses lock (e.g. Redlock) to preserve causality determined by `causality_key` (e.g. a tenant ID).
+
+
 ### Custom processors
 
 If you want to add some custom processor either for ActiveRecord or for custom service objects, create an object inheriting from `RailsTransactionalOutbox::RecordProcessors::BaseProcessor`, which has the following interface:

data/lib/rails_transactional_outbox/configuration.rb

@@ -4,7 +4,8 @@ class RailsTransactionalOutbox
   class Configuration
     attr_accessor :database_connection_provider, :logger, :outbox_model, :transaction_provider
     attr_writer :error_handler, :transactional_outbox_worker_sleep_seconds,
-      :transactional_outbox_worker_idle_delay_multiplier, :outbox_batch_size
+      :transactional_outbox_worker_idle_delay_multiplier, :outbox_batch_size, :outbox_entries_processor,
+      :lock_client, :lock_expiry_time, :outbox_entry_causality_key_resolver
 
     def error_handler
       @error_handler || RailsTransactionalOutbox::ErrorHandlers::NullErrorHandler
@@ -29,5 +30,21 @@ class RailsTransactionalOutbox
     def add_record_processor(record_processor)
       record_processors << record_processor
     end
+
+    def outbox_entries_processor
+      @outbox_entries_processor ||= RailsTransactionalOutbox::OutboxEntriesProcessors::NonOrderedProcessor.new
+    end
+
+    def lock_client
+      @lock_client || RailsTransactionalOutbox::NullLockClient
+    end
+
+    def lock_expiry_time
+      @lock_expiry_time || 10_000
+    end
+
+    def outbox_entry_causality_key_resolver
+      @outbox_entry_causality_key_resolver || ->(_model) {}
+    end
   end
 end

data/lib/rails_transactional_outbox/null_lock_client.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class RailsTransactionalOutbox
+  class NullLockClient
+    def self.lock(resource_key, expiration_time)
+      payload = {
+        validity: expiration_time,
+        resource: resource_key,
+        value: "null_lock_client_lock"
+      }
+
+      yield payload
+    end
+  end
+end

data/lib/rails_transactional_outbox/outbox_entries_processor.rb

@@ -9,48 +9,8 @@ class RailsTransactionalOutbox
       @config = config
     end
 
-    def call
-      return [] unless outbox_model.any_records_to_process?
-
-      transaction do
-        outbox_model.fetch_processable(outbox_batch_size).to_a.tap do |records_to_process|
-          failed_records = Concurrent::Array.new
-          # TODO: considering adding internal threads for better efficiency, these are just IO operations
-          # that don't require ordering of any kind
-          records_to_process.each do |record|
-            begin
-              process(record)
-            rescue => e
-              record.handle_error(e)
-              record.save!
-              failed_records << record
-            end
-            yield record if block_given?
-          end
-          processed_records = records_to_process - failed_records
-          mark_as_processed(processed_records)
-        end
-      end
-    end
-
-    private
-
-    delegate :outbox_model, :outbox_batch_size, :transaction_provider, to: :config
-    delegate :transaction, to: :transaction_provider
-
-    def mark_as_processed(processed_records)
-      outbox_model
-        .where(id: processed_records)
-        .update_all(processed_at: Time.current, error_class: nil, error_message: nil,
-          failed_at: nil, retry_at: nil)
-    end
-
-    def process(record)
-      record_processor.call(record)
-    end
-
-    def record_processor
-      @record_processor ||= RailsTransactionalOutbox::RecordProcessor.new
+    def call(&block)
+      config.outbox_entries_processor.call(&block)
     end
   end
 end

data/lib/rails_transactional_outbox/outbox_entries_processors/base_processor.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+class RailsTransactionalOutbox
+  class OutboxEntriesProcessors
+    class BaseProcessor
+      attr_reader :config
+      private     :config
+
+      def initialize(config: RailsTransactionalOutbox.configuration)
+        @config = config
+      end
+
+      def call(&block)
+        return [] unless outbox_model.any_records_to_process?
+
+        execute(&block)
+      end
+
+      private
+
+      delegate :outbox_model, :outbox_batch_size, to: :config
+
+      def execute(&_block)
+        raise "implement me"
+      end
+
+      def process_records(records_to_process, &block)
+        failed_records = []
+        records_to_process.each do |record|
+          begin
+            process(record)
+          rescue => e
+            record.handle_error(e)
+            record.save!
+            failed_records << record
+          end
+          yield record if block
+        end
+        processed_records = records_to_process - failed_records
+        mark_as_processed(processed_records)
+      end
+
+      def process(record)
+        record_processor.call(record)
+      end
+
+      def record_processor
+        @record_processor ||= RailsTransactionalOutbox::RecordProcessor.new
+      end
+
+      def mark_as_processed(processed_records)
+        outbox_model.mark_as_processed(processed_records)
+      end
+    end
+  end
+end

data/lib/rails_transactional_outbox/outbox_entries_processors/non_ordered_processor.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class RailsTransactionalOutbox
+  class OutboxEntriesProcessors
+    class NonOrderedProcessor < RailsTransactionalOutbox::OutboxEntriesProcessors::BaseProcessor
+      private
+
+      delegate :transaction_provider, to: :config
+      delegate :transaction, to: :transaction_provider
+
+      def execute(&block)
+        transaction do
+          outbox_model.fetch_processable(outbox_batch_size).to_a.tap do |records_to_process|
+            process_records(records_to_process, &block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails_transactional_outbox/outbox_entries_processors/ordered_by_causality_key_processor.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class RailsTransactionalOutbox
+  class OutboxEntriesProcessors
+    class OrderedByCausalityKeyProcessor < RailsTransactionalOutbox::OutboxEntriesProcessors::BaseProcessor
+      private
+
+      delegate :lock_client, :lock_expiry_time, to: :config
+
+      def execute(&block)
+        unprocessed_causality_keys.each_with_object([]) do |causality_key, processed_records|
+          lock_client.lock(lock_name(causality_key), lock_expiry_time) do |locked|
+            next unless locked
+
+            processed_records.concat(fetch_records(causality_key).tap { |records| process_records(records, &block) })
+          end
+        end
+      end
+
+      def unprocessed_causality_keys
+        outbox_model.unprocessed_causality_keys
+      end
+
+      def lock_name(causality_key)
+        "RailsTransactionalOutbox-#{causality_key}"
+      end
+
+      def fetch_records(causality_key)
+        outbox_model.fetch_processable_for_causality_key(outbox_batch_size, causality_key).to_a
+      end
+    end
+  end
+end

data/lib/rails_transactional_outbox/outbox_entries_processors.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class RailsTransactionalOutbox
+  class OutboxEntriesProcessors
+  end
+end

data/lib/rails_transactional_outbox/outbox_entry_factory.rb

@@ -10,18 +10,21 @@ class RailsTransactionalOutbox
     end
 
     def build(model, event_type)
-      config.outbox_model.new(attributes_for_entry(model, event_type))
+      outbox_model.new(attributes_for_entry(model, event_type))
     end
 
     private
 
+    delegate :outbox_model, :outbox_entry_causality_key_resolver, to: :config
+
     def attributes_for_entry(model, event_type)
       {
         resource_class: model.class.to_s,
         resource_id: model.id,
         changeset: model.saved_changes,
         event_name: "#{model.model_name.singular}_#{event_name_suffix(event_type)}",
-        context: RailsTransactionalOutbox::RecordProcessors::ActiveRecordProcessor.context
+        context: RailsTransactionalOutbox::RecordProcessors::ActiveRecordProcessor.context,
+        causality_key: outbox_entry_causality_key_resolver.call(model)
       }
     end
 

data/lib/rails_transactional_outbox/outbox_model.rb

@@ -6,17 +6,38 @@ class RailsTransactionalOutbox
 
     included do
       scope :fetch_processable, lambda { |batch_size|
-        where(processed_at: nil)
+        processable_now
           .lock("FOR UPDATE SKIP LOCKED")
-          .where("retry_at IS NULL OR retry_at <= ?", Time.current)
           .order(created_at: :asc)
           .limit(batch_size)
       }
 
-      def self.any_records_to_process?
+      scope :fetch_processable_for_causality_key, lambda { |batch_size, causality_key|
+        processable_now
+          .where(causality_key: causality_key)
+          .order(created_at: :asc)
+          .limit(batch_size)
+      }
+
+      scope :processable_now, lambda {
         where(processed_at: nil)
           .where("retry_at IS NULL OR retry_at <= ?", Time.current)
-          .exists?
+      }
+
+      def self.unprocessed_causality_keys
+        processable_now
+          .select("causality_key")
+          .distinct
+          .pluck(:causality_key)
+      end
+
+      def self.any_records_to_process?
+        processable_now.exists?
+      end
+
+      def self.mark_as_processed(processed_records)
+        where(id: processed_records).update_all(processed_at: Time.current, error_class: nil, error_message: nil,
+          failed_at: nil, retry_at: nil)
       end
 
       def self.outbox_encrypt_json_for(*encryptable_json_attributes)

data/lib/rails_transactional_outbox/version.rb

@@ -3,5 +3,5 @@
 class RailsTransactionalOutbox
   module Version
   end
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-transactional-outbox
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Karol Galanciak
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-08-31 00:00:00.000000000 Z
+date: 2022-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -139,7 +139,12 @@ files:
 - lib/rails_transactional_outbox/exponential_backoff.rb
 - lib/rails_transactional_outbox/health_check.rb
 - lib/rails_transactional_outbox/monitor.rb
+- lib/rails_transactional_outbox/null_lock_client.rb
 - lib/rails_transactional_outbox/outbox_entries_processor.rb
+- lib/rails_transactional_outbox/outbox_entries_processors.rb
+- lib/rails_transactional_outbox/outbox_entries_processors/base_processor.rb
+- lib/rails_transactional_outbox/outbox_entries_processors/non_ordered_processor.rb
+- lib/rails_transactional_outbox/outbox_entries_processors/ordered_by_causality_key_processor.rb
 - lib/rails_transactional_outbox/outbox_entry_factory.rb
 - lib/rails_transactional_outbox/outbox_model.rb
 - lib/rails_transactional_outbox/railtie.rb