acidic_job 1.0.0.pre6 → 1.0.0.pre9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9247c761078c570dfbacac2542bc8b7417c816bb9928f975bf7b92722a29f6a4
-  data.tar.gz: 8d36bb7517db0493d37eaf44aee901339a5d8d77411cad0e55fefe2d940137c6
+  metadata.gz: 3971aa5af368952620c483730c9a8a28efd9e01bffecc38d015d322e165bdffe
+  data.tar.gz: a6c7374d7e0f2121a0fc92b988c28cee29d488f32506dd84e9e84c15b0117eda
 SHA512:
-  metadata.gz: 47697f8b833d7061bacb2b6eaf1e6c15a9d6fec700db0891f881b8f945cf271e1c37adba9cde4572aed5d0e272767a690c172ece0937dbc212a90bc0dd02e8e5
-  data.tar.gz: cda551ac7a76a63199f03b19e7787ba0bfae414253b1e71b098b8304705458d0c8f21b1755f9f10c15b651d55b849469284754d6e585d13159ee4c28a17ed723
+  metadata.gz: 7a890818e15da5fb4f5990f9753545d2e33c2bfb6d6e2a9793a42efeed34fcb6dbef076b18111980b0bfe32fe58f490f5fad0d70640b8d6624c8ae0210b4dd8a
+  data.tar.gz: b988408714e535184d553982a8220e32c83e7551ea129a7a5c001f1e83462d03d64f86e7df4112fed3af51f1a8a197f38c587fd01a9dc0b4d77ea8051a43aee0

data/Gemfile.lock

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

data/README.md

@@ -78,7 +78,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 +99,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 +148,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
@@ -176,14 +176,13 @@ One final feature for those of you using Sidekiq Pro: an integrated DSL for Side
 In my opinion, any commercial software using Sidekiq should get Sidekiq Pro; it is _absolutely_ worth the money. If, however, you are using `acidic_job` in a non-commercial application, you could use the open-source dropin replacement for this functionality: https://github.com/breamware/sidekiq-batch
 
 ```ruby
-# TODO: write code sample
 class RideCreateJob < ActiveJob::Base
   include AcidicJob
 
   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
@@ -192,6 +191,53 @@ class RideCreateJob < ActiveJob::Base
 end
 ```
 
+## Testing
+
+When testing acidic jobs, you are likely to run into `ActiveRecord::TransactionIsolationError`s:
+
+```
+ActiveRecord::TransactionIsolationError: cannot set transaction isolation in a nested transaction
+```
+
+This error is thrown because by default RSpec and most MiniTest test suites use database transactions to keep the test database clean between tests. The database transaction that is wrapping all of the code executed in your test is run at the standard isolation level, but acidic jobs then try to create another transaction run at a more conservative isolation level. You cannot have a nested transaction that runs at a different isolation level, thus, this error. 
+
+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. 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:
+
+```ruby
+require "database_cleaner/active_record"
+
+# see https://github.com/DatabaseCleaner/database_cleaner#how-to-use
+RSpec.configure do |config|
+  config.use_transactional_fixtures = false
+
+  config.before(:suite) do
+    DatabaseCleaner.clean_with :truncation
+
+    # Here we are defaulting to :transaction but swapping to deletion for some specs;
+    # if your spec or its code-under-test uses
+    # nested transactions then specify :transactional e.g.:
+    #   describe "SomeWorker", :transactional do
+    #
+    DatabaseCleaner.strategy = :transaction
+
+    config.before(:context, transactional: true) { DatabaseCleaner.strategy = :deletion }
+    config.after(:context, transactional: true) { DatabaseCleaner.strategy = :transaction }
+    config.before(:context, type: :system) { DatabaseCleaner.strategy = :deletion }
+    config.after(:context, type: :system) { DatabaseCleaner.strategy = :transaction }
+  end
+
+  config.around(:each) do |example|
+    DatabaseCleaner.cleaning do
+      example.run
+    end
+  end
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/acidic_job/rspec_configuration.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "rspec"
+require "database_cleaner/active_record"
+
+# see https://github.com/DatabaseCleaner/database_cleaner#how-to-use
+RSpec.configure do |config|
+  config.use_transactional_fixtures = false
+
+  config.before(:suite) do
+    DatabaseCleaner.clean_with :truncation
+
+    # Here we are defaulting to :transaction but swapping to deletion for some specs;
+    # if your spec or its code-under-test uses
+    # nested transactions then specify :transactional e.g.:
+    #   describe "SomeWorker", :transactional do
+    #
+    DatabaseCleaner.strategy = :transaction
+
+    config.before(:context, transactional: true) { DatabaseCleaner.strategy = :deletion }
+    config.after(:context, transactional: true) { DatabaseCleaner.strategy = :transaction }
+    config.before(:context, type: :system) { DatabaseCleaner.strategy = :deletion }
+    config.after(:context, type: :system) { DatabaseCleaner.strategy = :transaction }
+  end
+
+  config.around(:each) do |example|
+    DatabaseCleaner.cleaning do
+      example.run
+    end
+  end
+end

data/lib/acidic_job/test_case.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "active_job/test_case"
+require "database_cleaner"
+
+module AcidicJob
+  class TestCase < ActiveJob::TestCase
+    self.use_transactional_tests = false if respond_to?(:use_transactional_tests)
+
+    def before_setup
+      @original_cleaners = DatabaseCleaner.cleaners
+      DatabaseCleaner.cleaners = transaction_free_cleaners_for(@original_cleaners)
+      super
+      DatabaseCleaner.start
+    end
+
+    def after_teardown
+      DatabaseCleaner.clean
+      super
+      DatabaseCleaner.cleaners = @original_cleaners
+    end
+
+    private
+
+    # Ensure 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.
+    def transaction_free_cleaners_for(original_cleaners)
+      non_transaction_cleaners = original_cleaners.dup.map do |(orm, opts), cleaner|
+        [[orm, opts], ensure_no_transaction_strategies_for(cleaner)]
+      end.to_h
+      DatabaseCleaner::Cleaners.new(non_transaction_cleaners)
+    end
+
+    def ensure_no_transaction_strategies_for(cleaner)
+      return cleaner unless strategy_name_for(cleaner) == "transaction"
+
+      cleaner.strategy = deletion_strategy_for(cleaner)
+      cleaner
+    end
+
+    def strategy_name_for(cleaner)
+      cleaner               # <DatabaseCleaner::Cleaner>
+        .strategy           # <DatabaseCleaner::ActiveRecord::Truncation>
+        .class              # DatabaseCleaner::ActiveRecord::Truncation
+        .name               # "DatabaseCleaner::ActiveRecord::Truncation"
+        .rpartition("::")   # ["DatabaseCleaner::ActiveRecord", "::", "Truncation"]
+        .last               # "Truncation"
+        .downcase           # "truncation"
+    end
+
+    def deletion_strategy_for(cleaner)
+      strategy = cleaner.strategy
+      strategy_namespace = strategy # <DatabaseCleaner::ActiveRecord::Truncation>
+                           .class                      # DatabaseCleaner::ActiveRecord::Truncation
+                           .name                       # "DatabaseCleaner::ActiveRecord::Truncation"
+                           .rpartition("::")           # ["DatabaseCleaner::ActiveRecord", "::", "Truncation"]
+                           .first                      # "DatabaseCleaner::ActiveRecord"
+      deletion_strategy_class_name = [strategy_namespace, "::", "Deletion"].join
+      deletion_strategy_class = deletion_strategy_class_name.constantize
+      instance_variable_hash = strategy.instance_variables.map do |var|
+        [
+          var.to_s.remove("@"),
+          strategy.instance_variable_get(var)
+        ]
+      end.to_h
+      options = instance_variable_hash.except("db", "connection_class")
+
+      deletion_strategy_class.new(**options)
+    end
+  end
+end

data/lib/acidic_job/version.rb

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

data/lib/acidic_job.rb

@@ -59,7 +59,7 @@ module AcidicJob
     end
   end
 
-  def with_acidity(given: {})
+  def with_acidity(providing: {})
     # execute the block to gather the info on what steps are defined for this job workflow
     @__acidic_job_steps = []
     steps = yield || []
@@ -76,7 +76,7 @@ module AcidicJob
     # 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)
 
-    @run = ensure_run_record(@__acidic_job_idempotency_key, workflow, given)
+    @run = ensure_run_record(@__acidic_job_idempotency_key, workflow, providing)
 
     # begin the workflow
     process_run(@run)
@@ -84,7 +84,7 @@ module AcidicJob
 
   # DEPRECATED
   def idempotently(with:, &blk)
-    with_acidity(given: with, &blk)
+    with_acidity(providing: with, &blk)
   end
 
   def safely_finish_acidic_job

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: acidic_job
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre6
+  version: 1.0.0.pre9
 platform: ruby
 authors:
 - fractaledmind
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-03-10 00:00:00.000000000 Z
+date: 2022-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -84,9 +84,11 @@ files:
 - lib/acidic_job/idempotency_key.rb
 - lib/acidic_job/perform_wrapper.rb
 - lib/acidic_job/recovery_point.rb
+- lib/acidic_job/rspec_configuration.rb
 - lib/acidic_job/run.rb
 - lib/acidic_job/staging.rb
 - lib/acidic_job/step.rb
+- lib/acidic_job/test_case.rb
 - lib/acidic_job/upgrade_service.rb
 - lib/acidic_job/version.rb
 - lib/generators/acidic_job/drop_tables_generator.rb