acidic_job 1.0.0.pre19 → 1.0.0.pre20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb1a8e3e2658bf86b44012171e33458c6e25803e41c255401575bc772cf033db
-  data.tar.gz: a2672fb1755af7ada91b7e8b156cffe951f22d530cbf7d94aee794622f9ad5c8
+  metadata.gz: e608eefef4baffbfb2c95dcbef942a53c9ca242c4c593ddbbe0d677ef7d318da
+  data.tar.gz: 65bed32739c1a1a860102e59dac69598c4357512034d8d3e87ed772469b9bac0
 SHA512:
-  metadata.gz: d6fc3314e1eb512ef9eab52cada5b7705891563715f1d549912b45b13b85bd0bf778a8950a5657037ddf75e7e81819cf8c85a240c191cb71d615e98ca22c7c3a
-  data.tar.gz: 011f57cb97e93bd6e09c2c07d164d06679c8311b8e76a1b1cf9438376e65da5d4d76851cd7e1b6eb4d2f1ffba7064ff722c8cec75db08e78a1e96b7353672d13
+  metadata.gz: 5a5f6155e20f929c631392f00480f57928455778e13117609457be9b8624e7f16c41661df96ae34a4045582f957b044cbdf811bfa7e187dd627b8b72b80edb90
+  data.tar.gz: 6a663d288bd1ef3ba5cfac8e137fd496ebbca76e08573e50d706ed2570c98b6fe3148b8c9335b55313a091ccd0cc226e3b9023878dd418d400af33fd0280c1b4

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    acidic_job (1.0.0.pre19)
+    acidic_job (1.0.0.pre20)
       activerecord
       activesupport
       database_cleaner

data/README.md

@@ -68,8 +68,10 @@ It provides a suite of functionality that empowers you to create complex, robust
 * 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
+* Iterable Steps — define steps that iterate over some collection fully until moving on to the next step
 * 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
+* Run Finished Callbacks — set callbacks for when a job run finishes fully
 
 ### Transactional Steps
 
@@ -80,9 +82,10 @@ class RideCreateJob < ActiveJob::Base
   include AcidicJob
 
   def perform(user_id, ride_params)
-    user = User.find(user_id)
+    @user = User.find(user_id)
+    @params = ride_params
 
-    with_acidity providing: { user: user, params: ride_params, ride: nil } do
+    with_acidity providing: { ride: nil } do
       step :create_ride_and_audit_record
       step :create_stripe_charge
       step :send_receipt
@@ -128,7 +131,7 @@ class RideCreateJob < ActiveJob::Base
   end
 
   def create_stripe_charge
-    Stripe::Charge.create(amount: 20_00, customer: self.ride.user)
+    Stripe::Charge.create(amount: 20_00, customer: @ride.user)
   end
 
   # ...
@@ -139,6 +142,8 @@ end
 
 **Note:** You will note the use of `self.ride = ...` in the code sample above. In order to call the attribute setter method that will sync with the database record, you _must_ use this style. `@ride = ...` and/or `ride = ...` will both fail to sync the value with the database record.
 
+The default pattern you should follow when defining your `perform` method is to make any values that your `step` methods need access to, but are present at the start of the `perform` method simply instance variables. You only need to `provide` attributes that will be set _during a step_. This means, the initial value will almost always be `nil`.
+
 ### Transactionally Staged Jobs
 
 A standard problem when inside of database transactions is enqueuing other jobs. On the one hand, you could enqueue a job inside of a transaction that then rollbacks, which would leave that job to fail and retry and fail. On the other hand, you could enqueue a job that is picked up before the transaction commits, which would mean the records are not yet available to this job.
@@ -150,9 +155,10 @@ class RideCreateJob < ActiveJob::Base
   include AcidicJob
 
   def perform(user_id, ride_params)
-    user = User.find(user_id)
+    @user = User.find(user_id)
+    @params = ride_params
     
-    with_acidity providing: { user: user, params: ride_params, ride: nil } do
+    with_acidity providing: { ride: nil } do
       step :create_ride_and_audit_record
       step :create_stripe_charge
       step :send_receipt
@@ -211,6 +217,28 @@ end
 
 > **Note:** The signature of the `acidic_by` proc _needs to match the signature_ of the job's `perform` method.
 
+### Iterable Steps
+
+Sometimes our workflows have steps that need to iterate over a collection and perform an action for each item in the collection before moving on to the next step in the workflow. In these cases, we can use the `for_each` option when defining our step to specific the collection, and `acidic_job` will pass each item into your step method for processing, keeping the same transactional guarantees as for any step. This means that if your step encounters an error in processing any item in the collection, when your job is retried, the job will jump right back to that step and right back to that item in the collection to try again.
+
+```ruby
+class ExampleJob < ActiveJob::Base
+  include AcidicJob
+
+  def perform(record:)
+    with_acidity providing: { collection: [1, 2, 3, 4, 5] } do
+      step :process_item, for_each: :collection
+      step :next_step
+    end
+  end
+  
+  def process_item(item)
+    # do whatever work needs to be done with this individual item
+  end
+end
+```
+
+**Note:** The same restrictions apply here as for any persisted attribute — you can only use objects that can be serialized by ActiveRecord.
 
 ### Sidekiq Callbacks
 
@@ -229,9 +257,10 @@ class RideCreateJob < ActiveJob::Base
   include AcidicJob
 
   def perform(user_id, ride_params)
-    user = User.find(user_id)
+    @user = User.find(user_id)
+    @params = ride_params
 
-    with_acidity providing: { user: user, params: ride_params, ride: nil } do
+    with_acidity providing: { 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
@@ -240,6 +269,36 @@ class RideCreateJob < ActiveJob::Base
 end
 ```
 
+### Run Finished Callbacks
+
+When working with workflow jobs that make use of the `awaits` feature for a step, it is important to remember that the `after_perform` callback will be called _as soon as the first `awaits` step has enqueued job_, and **not** when the entire job run has finished. `acidic_job` allows the `perform` method to finish so that the queue for the workflow job is cleared to pick up new work while the `awaits` jobs are running. `acidic_job` will automatically re-enqueue the workflow job and progress to the next step when all of the `awaits` jobs have successfully finished. However, this means that `after_perform` **is not necessarily** the same as `after_finish`. In order to provide the opportunity for you to execute callback logic _if and only if_ a job run has finished, we provide callback hooks for the `finish` event.
+
+For example, you could use this hook to immediately clean up the `AcidicJob::Run` database record whenever the workflow job finishes successfully like so:
+
+```ruby
+class RideCreateJob < ActiveJob::Base
+  include AcidicJob
+  set_callback :finish, :after, :delete_run_record
+
+  def perform(user_id, ride_params)
+    @user = User.find(user_id)
+    @params = ride_params
+
+    with_acidity providing: { 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
+    end
+  end
+  
+  def delete_run_record
+    return unless acidic_job_run.succeeded?
+
+    acidic_job_run.destroy!
+  end
+end
+```
+
 ## Testing
 
 When testing acidic jobs, you are likely to run into `ActiveRecord::TransactionIsolationError`s:

data/lib/acidic_job/version.rb

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

data/lib/acidic_job.rb

@@ -55,6 +55,7 @@ module AcidicJob
     klass.define_singleton_method(:acidic_by_job_id) { @acidic_identifier = :job_id }
     klass.define_singleton_method(:acidic_by_job_args) { @acidic_identifier = :job_args }
     klass.define_singleton_method(:acidic_by) { |proc| @acidic_identifier = proc }
+    klass.attr_reader(:acidic_job_run)
   end
 
   included do
@@ -96,10 +97,10 @@ module AcidicJob
     # convert the array of steps into a hash of recovery_points and next steps
     workflow = define_workflow(@__acidic_job_steps)
 
-    @run = ensure_run_record(workflow, providing)
+    @acidic_job_run = ensure_run_record(workflow, providing)
 
     # begin the workflow
-    process_run(@run)
+    process_run(@acidic_job_run)
   end
 
   # DEPRECATED

metadata

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