acidic_job 1.0.0.pre10 → 1.0.0.pre11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95b8fbdebe38a639f9b905df6ac1f5b853b09383d0810696c89c6c9e001efffe
-  data.tar.gz: b7e92f9b98461e2f39122405b6e3278fb7ed8a0edec65963026f7e2665bb5042
+  metadata.gz: 53b5f12879bffb6a461e3574b96f8a41464ec83ce0a21eaa8e244261ce53a9be
+  data.tar.gz: 7b90c9864347564706466e62c61f08eb377d8e3a33475ad40ba559de59e7b70e
 SHA512:
-  metadata.gz: 13b5ea59163e833f5b698625d841fdcdc0a630b46880526df3274926e696b227b41946fd6622e121b9afd90ad3cc94589f6e864188e871d70f03c77168e3ad5e
-  data.tar.gz: 27e5b74147706f227875f4f4a61f084298c42e615149cb0a74670af841df8fcce9eb4f95d11935561912af61d6d8759c21c9ca9862e897f765b49c78b1e42ebd
+  metadata.gz: '08b4a0bdd41ac80f8ac879003f455f577f93fc431acdb780dfd3e54260b07a61bf0557c3e7d99192e1ad809134b709211fd2c5efe581b797563187dcfbb34467'
+  data.tar.gz: 66e8b3bfe0226c3e1f5168d45431a01a36ee3dfb796c855c49fc009296cb223d33922bc2db5febbe6d6453b4a01c46661b805aa1e2c80a4e37f3dce183b5e748

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    acidic_job (1.0.0.pre10)
+    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
 
@@ -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).

data/lib/acidic_job/extensions/action_mailer.rb

@@ -7,17 +7,15 @@ module AcidicJob
     module ActionMailer
       extend ActiveSupport::Concern
 
-      def deliver_acidicly(_options = {}, idempotency_key: nil, unique_by: nil)
+      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_class.new(job_args).serialize
         acidic_identifier = job_class.respond_to?(:acidic_identifier) ? job_class.acidic_identifier : :job_id
-        # use either [1] provided key, [2] provided uniqueness constraint, or [3] computed key
-        key = if idempotency_key
-                idempotency_key
-              elsif unique_by
+        # 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)

data/lib/acidic_job/extensions/active_job.rb

@@ -24,10 +24,8 @@ module AcidicJob
           raise UnsupportedExtension unless defined?(::ActiveJob) && self < ::ActiveJob::Base
 
           serialized_job = serialize_with_arguments(*args, **kwargs)
-          # use either [1] provided key, [2] provided uniqueness constraint, or [3] computed key
-          key = if kwargs.key?(:idempotency_key) || kwargs.key?("idempotency_key")
-                  kwargs[:idempotency_key] || kwargs["idempotency_key"]
-                elsif kwargs.key?(:unique_by) || kwargs.key?("unique_by")
+          # 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

data/lib/acidic_job/extensions/noticed.rb

@@ -6,12 +6,12 @@ module AcidicJob
       extend ActiveSupport::Concern
 
       class_methods do
-        def deliver_acidicly(recipients, idempotency_key: nil, unique_by: nil)
-          new.deliver_acidicly(recipients, idempotency_key: idempotency_key, unique_by: unique_by)
+        def deliver_acidicly(recipients, unique_by: nil)
+          new.deliver_acidicly(recipients, unique_by: unique_by)
         end
       end
 
-      def deliver_acidicly(recipients, idempotency_key: nil, unique_by: nil)
+      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
@@ -37,10 +37,8 @@ module AcidicJob
             }
             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 key, [2] provided uniqueness constraint, or [3] computed key
-            key = if idempotency_key
-                    idempotency_key
-                  elsif unique_by
+            # 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)

data/lib/acidic_job/extensions/sidekiq.rb

@@ -58,10 +58,8 @@ module AcidicJob
         class_methods do
           def perform_acidicly(*args, **kwargs)
             serialized_job = serialize_with_arguments(*args, **kwargs)
-            # use either [1] provided key, [2] provided uniqueness constraint, or [3] computed key
-            key = if kwargs.key?(:idempotency_key) || kwargs.key?("idempotency_key")
-                    kwargs[:idempotency_key] || kwargs["idempotency_key"]
-                  elsif kwargs.key?(:unique_by) || kwargs.key?("unique_by")
+            # 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

data/lib/acidic_job/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: acidic_job
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre10
+  version: 1.0.0.pre11
 platform: ruby
 authors:
 - fractaledmind