acidic_job 1.0.0.pre8 → 1.0.0.pre11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ed45351f35a4450eebc153e9bff2eba2a8c5cd1dcf5b121f9fa9c9e5e910936
-  data.tar.gz: a4eff2b6a54ab1e89fab5b548022e3104540e118694f45bc42ebaf6b8e5cadb1
+  metadata.gz: 53b5f12879bffb6a461e3574b96f8a41464ec83ce0a21eaa8e244261ce53a9be
+  data.tar.gz: 7b90c9864347564706466e62c61f08eb377d8e3a33475ad40ba559de59e7b70e
 SHA512:
-  metadata.gz: 79ebea1341fcab4b84b4534b0a6aa468c1b1b96813bd687744c5caff97050ec62a2af51f6c89b8631801774b06babfb5044233b5e060383051bc33ff4bc8338c
-  data.tar.gz: b10c9a7c05c8bd4079a35f865a1c31cef193ccfd2219718cb0df453272211ad2c62772db14763e4244752f6c2c8666a3ef5eb512b07bff7ffa75325d41ccf68e
+  metadata.gz: '08b4a0bdd41ac80f8ac879003f455f577f93fc431acdb780dfd3e54260b07a61bf0557c3e7d99192e1ad809134b709211fd2c5efe581b797563187dcfbb34467'
+  data.tar.gz: 66e8b3bfe0226c3e1f5168d45431a01a36ee3dfb796c855c49fc009296cb223d33922bc2db5febbe6d6453b4a01c46661b805aa1e2c80a4e37f3dce183b5e748

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    acidic_job (1.0.0.pre8)
+    acidic_job (1.0.0.pre11)
       activerecord (>= 6.1.0)
       activesupport
 

data/README.md

@@ -64,6 +64,7 @@ It provides a suite of functionality that empowers you to create complex, robust
 * Transactional Steps — break your job into a series of steps, each of which will be run within an acidic database transaction, allowing retries to jump back to the last "recovery point".
 * Persisted Attributes — when retrying jobs at later steps, we need to ensure that data created in previous steps is still available to later steps on retry.
 * Transactionally Staged Jobs — enqueue additional jobs within the acidic transaction safely
+* Custom Idempotency Keys — use something other than the job ID for the idempotency key of the job run
 * Sidekiq Callbacks — bring ActiveJob-like callbacks into your pure Sidekiq Workers
 * Sidekiq Batches — leverage the power of Sidekiq Pro's `batch` functionality without the hassle
 
@@ -78,7 +79,7 @@ class RideCreateJob < ActiveJob::Base
   def perform(user_id, ride_params)
     user = User.find(user_id)
 
-    with_acidity given: { user: user, params: ride_params, ride: nil } do
+    with_acidity providing: { user: user, params: ride_params, ride: nil } do
       step :create_ride_and_audit_record
       step :create_stripe_charge
       step :send_receipt
@@ -99,20 +100,20 @@ class RideCreateJob < ActiveJob::Base
 end
 ```
 
-`with_acidity` takes only the `given:` named parameter and a block where you define the steps of this operation. `step` simply takes the name of a method available in the job. That's all!
+`with_acidity` takes only the `providing:` named parameter and a block where you define the steps of this operation. `step` simply takes the name of a method available in the job. That's all!
 
 Now, each execution of this job will find or create an `AcidicJob::Run` record, which we leverage to wrap every step in a database transaction. Moreover, this database record allows `acidic_job` to ensure that if your job fails on step 3, when it retries, it will simply jump right back to trying to execute the method defined for the 3rd step, and won't even execute the first two step methods. This means your step methods only need to be idempotent on failure, not on success, since they will never be run again if they succeed.
 
 ### Persisted Attributes
 
-Any objects passed to the `given` option on the `with_acidity` method are not just made available to each of your step methods, they are made available across retries. This means that you can set an attribute in step 1, access it in step 2, have step 2 fail, have the job retry, jump directly back to step 2 on retry, and have that object still accessible. This is done by serializing all objects to a field on the `AcidicJob::Run` and manually providing getters and setters that sync with the database record.
+Any objects passed to the `providing` option on the `with_acidity` method are not just made available to each of your step methods, they are made available across retries. This means that you can set an attribute in step 1, access it in step 2, have step 2 fail, have the job retry, jump directly back to step 2 on retry, and have that object still accessible. This is done by serializing all objects to a field on the `AcidicJob::Run` and manually providing getters and setters that sync with the database record.
 
 ```ruby
 class RideCreateJob < ActiveJob::Base
   include AcidicJob
 
   def perform(ride_params)
-    with_acidity given: { ride: nil } do
+    with_acidity providing: { ride: nil } do
       step :create_ride_and_audit_record
       step :create_stripe_charge
       step :send_receipt
@@ -148,7 +149,7 @@ class RideCreateJob < ActiveJob::Base
   def perform(user_id, ride_params)
     user = User.find(user_id)
     
-    with_acidity given: { user: user, params: ride_params, ride: nil } do
+    with_acidity providing: { user: user, params: ride_params, ride: nil } do
       step :create_ride_and_audit_record
       step :create_stripe_charge
       step :send_receipt
@@ -163,6 +164,47 @@ class RideCreateJob < ActiveJob::Base
 end
 ```
 
+### Custom Idempotency Keys
+
+By default, `AcidicJob` uses the job identifier provided by the queueing system (ActiveJob or Sidekiq) as the idempotency key for the job run. The idempotency key is what is used to guarantee that no two runs of the same job occur. However, sometimes we need particular jobs to be idempotent based on some other criteria. In these cases, `AcidicJob` provides a collection of tools to allow you to ensure the idempotency of your jobs.
+
+Firstly, you can configure your job class to explicitly use either the job identifier or the job arguments as the foundation for the idempotency key. A job class that calls the `acidic_by_job_id` class method (which is the default behavior) will simply make the job run's idempotency key the job's identifier:
+
+```ruby
+class ExampleJob < ActiveJob::Base
+  include AcidicJob
+  acidic_by_job_id
+
+  def perform
+  end
+end
+```
+
+Conversely, a job class can use the `acidic_by_job_args` method to configure that job class to use the arguments passed to the job as the foundation for the job run's idempotency key:
+
+```ruby
+class ExampleJob < ActiveJob::Base
+  include AcidicJob
+  acidic_by_job_args
+
+  def perform(arg_1, arg_2)
+    # the idempotency key will be based on whatever the values of `arg_1` and `arg_2` are
+  end
+end
+```
+
+These options cover the two common situations, but sometimes our systems need finer-grained control. For example, our job might take some record as the job argument, but we need to use a combination of the record identifier and record status as the foundation for the idempotency key. In these cases we can't configure the idempotency key logic at the class level, so instead we can provide the logic when enqueuing the job itself.
+
+When you call any `deliver_acidicly` or `perform_acidicly` method you can pass an optional `unique_by` argument which will be used to generate the idempotency key:
+
+```ruby
+ExampleJob.perform_acidicly(unique_by: { id: record.id, status: record.status })
+UserMailer.with(user, record).deliver_acidicly(unique_by: [user.id, record.id, record.status])
+```
+
+As you see, the value to the `unique_by` option can be a Hash or an Array or even a simple scalar value.
+
+
 ### Sidekiq Callbacks
 
 In order to ensure that `AcidicJob::Staged` records are only destroyed once the related job has been successfully performed, whether it is an ActiveJob or a Sidekiq Worker, `acidic_job` also extends Sidekiq to support the [ActiveJob callback interface](https://edgeguides.rubyonrails.org/active_job_basics.html#callbacks).
@@ -182,7 +224,7 @@ class RideCreateJob < ActiveJob::Base
   def perform(user_id, ride_params)
     user = User.find(user_id)
 
-    with_acidity given: { user: user, params: ride_params, ride: nil } do
+    with_acidity providing: { user: user, params: ride_params, ride: nil } do
       step :create_ride_and_audit_record, awaits: [SomeJob]
       step :create_stripe_charge, args: [1, 2, 3], kwargs: { some: 'thing' }
       step :send_receipt
@@ -203,25 +245,7 @@ This error is thrown because by default RSpec and most MiniTest test suites use
 
 In order to avoid this error, you need to ensure firstly that your tests that run your acidic jobs are not using a database transaction and secondly that they use some different strategy to keep your test database clean. The [DatabaseCleaner](https://github.com/DatabaseCleaner/database_cleaner) gem is a commonly used tool to manage different strategies for keeping your test database clean. As for which strategy to use, `truncation` and `deletion` are both safe, but their speed varies based on our app's table structure (see https://github.com/DatabaseCleaner/database_cleaner#what-strategy-is-fastest). Either is fine; use whichever is faster for your app.
 
-In order to make this test setup simpler, `AcidicJob` provides a `TestCase` class that your MiniTest jobs tests can inherit from. It is simple; it inherits from `ActiveJob::TestCase`, sets `use_transactional_tests` to `false`, and ensures `DatabaseCleaner` is run for each of your tests:
-
-```ruby
-class AcidicJob::TestCase < ActiveJob::TestCase
-  self.use_transactional_tests = false
-
-  def before_setup
-    super
-    DatabaseCleaner.start
-  end
-
-  def after_teardown
-    DatabaseCleaner.clean
-    super
-  end
-
-  # ...
-end
-```
+In order to make this test setup simpler, `AcidicJob` provides a `TestCase` class that your MiniTest jobs tests can inherit from. It is simple; it inherits from `ActiveJob::TestCase`, sets `use_transactional_tests` to `false`, and ensures `DatabaseCleaner` is run for each of your tests. Moreover, it ensures that the system's original DatabaseCleaner configuration is maintained, options included, except that any `transaction` strategies for any ORMs are replaced with a `deletion` strategy. It does so by storing whatever the system DatabaseCleaner configuration is at the start of `before_setup` phase in an instance variable and then restores that configuration at the end of `after_teardown` phase. In between, it runs the configuration thru a pipeline that selectively replaces any `transaction` strategies with a corresponding `deletion` strategy, leaving any other configured strategies untouched.
 
 For those of you using RSpec, you can require the `acidic_job/rspec_configuration` file, which will configure RSpec in the exact same way I have used in my RSpec projects to allow me to test acidic jobs with either the `deletion` strategy but still have all of my other tests use the fast `transaction` strategy:
 

data/lib/acidic_job/extensions/action_mailer.rb

@@ -7,18 +7,25 @@ module AcidicJob
     module ActionMailer
       extend ActiveSupport::Concern
 
-      def deliver_acidicly(_options = {})
-        job = ::ActionMailer::MailDeliveryJob
+      def deliver_acidicly(_options = {}, unique_by: nil)
+        job_class = ::ActionMailer::MailDeliveryJob
 
         job_args = [@mailer_class.name, @action.to_s, "deliver_now", @params, *@args]
         # for Sidekiq, this depends on the Sidekiq::Serialization extension
-        serialized_job = job.new(job_args).serialize
+        serialized_job = job_class.new(job_args).serialize
+        acidic_identifier = job_class.respond_to?(:acidic_identifier) ? job_class.acidic_identifier : :job_id
+        # use either [1] provided uniqueness constraint or [2] computed key
+        key = if unique_by
+                IdempotencyKey.generate(unique_by: unique_by, job_class: job_class.name)
+              else
+                IdempotencyKey.new(acidic_identifier).value_for(serialized_job)
+              end
 
         AcidicJob::Run.create!(
           staged: true,
-          job_class: job.name,
+          job_class: job_class.name,
           serialized_job: serialized_job,
-          idempotency_key: IdempotencyKey.value_for(serialized_job)
+          idempotency_key: key
         )
       end
       alias deliver_transactionally deliver_acidicly

data/lib/acidic_job/extensions/active_job.rb

@@ -24,12 +24,19 @@ module AcidicJob
           raise UnsupportedExtension unless defined?(::ActiveJob) && self < ::ActiveJob::Base
 
           serialized_job = serialize_with_arguments(*args, **kwargs)
+          # use either [1] provided uniqueness constraint or [2] computed key
+          key = if kwargs.key?(:unique_by) || kwargs.key?("unique_by")
+                  unique_by = [kwargs[:unique_by], kwargs["unique_by"]].compact.first
+                  IdempotencyKey.generate(unique_by: unique_by, job_class: name)
+                else
+                  IdempotencyKey.new(acidic_identifier).value_for(serialized_job)
+                end
 
           AcidicJob::Run.create!(
             staged: true,
             job_class: name,
             serialized_job: serialized_job,
-            idempotency_key: IdempotencyKey.value_for(serialized_job)
+            idempotency_key: key
           )
         end
         alias_method :perform_transactionally, :perform_acidicly

data/lib/acidic_job/extensions/noticed.rb

@@ -6,12 +6,12 @@ module AcidicJob
       extend ActiveSupport::Concern
 
       class_methods do
-        def deliver_acidicly(recipients)
-          new.deliver_acidicly(recipients)
+        def deliver_acidicly(recipients, unique_by: nil)
+          new.deliver_acidicly(recipients, unique_by: unique_by)
         end
       end
 
-      def deliver_acidicly(recipients)
+      def deliver_acidicly(recipients, unique_by: nil)
         # THIS IS A HACK THAT COPIES AND PASTES KEY PARTS OF THE `Noticed::Base` CODE
         # IN ORDER TO ALLOW US TO TRANSACTIONALLY DELIVER NOTIFICATIONS
         # THIS IS THUS LIABLE TO BREAK WHENEVER THAT GEM IS UPDATED
@@ -36,12 +36,19 @@ module AcidicJob
               record: record
             }
             serialized_job = job_class.send(:job_or_instantiate, args).serialize
+            acidic_identifier = job_class.respond_to?(:acidic_identifier) ? job_class.acidic_identifier : :job_id
+            # use either [1] provided uniqueness constraint or [2] computed key
+            key = if unique_by
+                    IdempotencyKey.generate(unique_by: unique_by, job_class: job_class.name)
+                  else
+                    IdempotencyKey.new(acidic_identifier).value_for(serialized_job)
+                  end
 
             AcidicJob::Run.create!(
               staged: true,
               job_class: job_class.name,
               serialized_job: serialized_job,
-              idempotency_key: IdempotencyKey.value_for(serialized_job)
+              idempotency_key: key
             )
           end
         end

data/lib/acidic_job/extensions/sidekiq.rb

@@ -58,12 +58,19 @@ module AcidicJob
         class_methods do
           def perform_acidicly(*args, **kwargs)
             serialized_job = serialize_with_arguments(*args, **kwargs)
+            # use either [1] provided uniqueness constraint or [2] computed key
+            key = if kwargs.key?(:unique_by) || kwargs.key?("unique_by")
+                    unique_by = [kwargs[:unique_by], kwargs["unique_by"]].compact.first
+                    IdempotencyKey.generate(unique_by: unique_by, job_class: name)
+                  else
+                    IdempotencyKey.new(acidic_identifier).value_for(serialized_job)
+                  end
 
             AcidicJob::Run.create!(
               staged: true,
               job_class: name,
               serialized_job: serialized_job,
-              idempotency_key: IdempotencyKey.value_for(serialized_job)
+              idempotency_key: key
             )
           end
           alias_method :perform_transactionally, :perform_acidicly

data/lib/acidic_job/idempotency_key.rb

@@ -2,15 +2,57 @@
 
 module AcidicJob
   class IdempotencyKey
-    def self.value_for(hash_or_job, *args, **kwargs)
-      return hash_or_job.job_id if hash_or_job.respond_to?(:job_id) && !hash_or_job.job_id.nil?
-      return hash_or_job.jid if hash_or_job.respond_to?(:jid) && !hash_or_job.jid.nil?
+    def self.generate(unique_by:, job_class:)
+      new(:job_args).value_for({ "job_class" => job_class }, Marshal.dump(unique_by))
+    end
+
+    def initialize(identifier = :job_id)
+      @identifier = identifier
+    end
+
+    def value_for(hash_or_job, *args, **kwargs)
+      return value_from_job_args(hash_or_job, *args, **kwargs) if @identifier == :job_args
+
+      value = if hash_or_job.is_a?(Hash)
+                value_from_job_id_for_hash(hash_or_job)
+              else
+                value_from_job_id_for_obj(hash_or_job)
+              end
+
+      value || value_from_job_args(hash_or_job, *args, **kwargs)
+    end
+
+    private
 
-      if hash_or_job.is_a?(Hash) && hash_or_job.key?("job_id") && !hash_or_job["job_id"].nil?
-        return hash_or_job["job_id"]
+    def value_from_job_id_for_hash(hash)
+      if hash.key?("job_id")
+        return if hash["job_id"].nil?
+        return if hash["job_id"].empty?
+
+        hash["job_id"]
+      elsif hash.key?("jid")
+        return if hash["jid"].nil?
+        return if hash["jid"].empty?
+
+        hash["jid"]
+      end
+    end
+
+    def value_from_job_id_for_obj(obj)
+      if obj.respond_to?(:job_id)
+        return if obj.job_id.nil?
+        return if obj.job_id.empty?
+
+        obj.job_id
+      elsif obj.respond_to?(:jid)
+        return if obj.jid.nil?
+        return if obj.jid.empty?
+
+        obj.jid
       end
-      return hash_or_job["jid"] if hash_or_job.is_a?(Hash) && hash_or_job.key?("jid") && !hash_or_job["jid"].nil?
+    end
 
+    def value_from_job_args(hash_or_job, *args, **kwargs)
       worker_class = case hash_or_job
                      when Hash
                        hash_or_job["worker"] || hash_or_job["job_class"]

data/lib/acidic_job/staging.rb

@@ -26,5 +26,15 @@ module AcidicJob
 
       GlobalID::Locator.locate(staged_job_gid)
     end
+
+    def identifier
+      return jid if defined?(jid) && !jid.nil?
+      return job_id if defined?(job_id) && !job_id.nil?
+
+      # might be defined already in `with_acidity` method
+      @__acidic_job_idempotency_key ||= IdempotencyKey.value_for(self, @__acidic_job_args, @__acidic_job_kwargs)
+
+      @__acidic_job_idempotency_key
+    end
   end
 end

data/lib/acidic_job/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AcidicJob
-  VERSION = "1.0.0.pre8"
+  VERSION = "1.0.0.pre11"
 end

data/lib/acidic_job.rb

@@ -46,6 +46,10 @@ module AcidicJob
     end
 
     klass.set_callback :perform, :after, :delete_staged_job_record, if: :was_staged_job?
+
+    klass.instance_variable_set(:@acidic_identifier, :job_id)
+    klass.define_singleton_method(:acidic_by_job_id) { @acidic_identifier = :job_id }
+    klass.define_singleton_method(:acidic_by_job_args) { @acidic_identifier = :job_args }
   end
 
   included do
@@ -57,34 +61,35 @@ module AcidicJob
       AcidicJob.wire_everything_up(subclass)
       super
     end
+
+    def acidic_identifier
+      @acidic_identifier
+    end
   end
 
-  def with_acidity(given: {})
-    # execute the block to gather the info on what steps are defined for this job workflow
+  def with_acidity(providing: {})
+    # ensure this instance variable is always defined
     @__acidic_job_steps = []
-    steps = yield || []
+    # execute the block to gather the info on what steps are defined for this job workflow
+    yield
 
     # check that the block actually defined at least one step
     # TODO: WRITE TESTS FOR FAULTY BLOCK VALUES
     raise NoDefinedSteps if @__acidic_job_steps.nil? || @__acidic_job_steps.empty?
 
     # convert the array of steps into a hash of recovery_points and next steps
-    workflow = define_workflow(steps)
-
-    # determine the idempotency key value for this job run (`job_id` or `jid`)
-    # might be defined already in `identifier` method
-    # TODO: allow idempotency to be defined by args OR job id
-    @__acidic_job_idempotency_key ||= IdempotencyKey.value_for(self, @__acidic_job_args, @__acidic_job_kwargs)
+    workflow = define_workflow(@__acidic_job_steps)
 
-    @run = ensure_run_record(@__acidic_job_idempotency_key, workflow, given)
+    @run = ensure_run_record(workflow, providing)
 
     # begin the workflow
     process_run(@run)
   end
 
   # DEPRECATED
-  def idempotently(with:, &blk)
-    with_acidity(given: with, &blk)
+  def idempotently(with: {}, &blk)
+    ActiveSupport::Deprecation.new("1.0", "AcidicJob").deprecation_warning(:idempotently)
+    with_acidity(providing: with, &blk)
   end
 
   def safely_finish_acidic_job
@@ -93,11 +98,16 @@ module AcidicJob
     FinishedPoint.new
   end
 
+  # TODO: allow idempotency to be defined by args OR job id
   # rubocop:disable Naming/MemoizedInstanceVariableName
   def idempotency_key
-    return @__acidic_job_idempotency_key if defined? @__acidic_job_idempotency_key
+    if defined?(@__acidic_job_idempotency_key) && !@__acidic_job_idempotency_key.nil?
+      return @__acidic_job_idempotency_key
+    end
 
-    @__acidic_job_idempotency_key ||= IdempotencyKey.value_for(self, @__acidic_job_args, @__acidic_job_kwargs)
+    acidic_identifier = self.class.acidic_identifier
+    @__acidic_job_idempotency_key ||= IdempotencyKey.new(acidic_identifier)
+                                                    .value_for(self, @__acidic_job_args, @__acidic_job_kwargs)
   end
   # rubocop:enable Naming/MemoizedInstanceVariableName
 
@@ -171,7 +181,7 @@ module AcidicJob
     # { "step 1": { does: "step 1", awaits: [], then: "step 2" }, ...  }
   end
 
-  def ensure_run_record(key_val, workflow, accessors)
+  def ensure_run_record(workflow, accessors)
     isolation_level = case ActiveRecord::Base.connection.adapter_name.downcase.to_sym
                       when :sqlite
                         :read_uncommitted
@@ -180,7 +190,7 @@ module AcidicJob
                       end
 
     ActiveRecord::Base.transaction(isolation: isolation_level) do
-      run = Run.find_by(idempotency_key: key_val)
+      run = Run.find_by(idempotency_key: idempotency_key)
       serialized_job = serialize_job(@__acidic_job_args, @__acidic_job_kwargs)
 
       if run.present?
@@ -201,7 +211,7 @@ module AcidicJob
       else
         run = Run.create!(
           staged: false,
-          idempotency_key: key_val,
+          idempotency_key: idempotency_key,
           job_class: self.class.name,
           locked_at: Time.current,
           last_run_at: Time.current,
@@ -246,14 +256,4 @@ module AcidicJob
 
     true
   end
-
-  def identifier
-    return jid if defined?(jid) && !jid.nil?
-    return job_id if defined?(job_id) && !job_id.nil?
-
-    # might be defined already in `with_acidity` method
-    @__acidic_job_idempotency_key ||= IdempotencyKey.value_for(self, @__acidic_job_args, @__acidic_job_kwargs)
-
-    @__acidic_job_idempotency_key
-  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: acidic_job
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre8
+  version: 1.0.0.pre11
 platform: ruby
 authors:
 - fractaledmind
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-03-12 00:00:00.000000000 Z
+date: 2022-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord