acidic_job 0.1.5 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c51b3ed20bebb6322ab050f122c83d863fe16436e302b61f91eea84fd9cc117
-  data.tar.gz: 7f65a1d6c99d23930c4730557388833b3ebd277117394b18d6665978bf35119d
+  metadata.gz: bcdd5a6f2496a5764d0d0b07f1263653a299d2dd2594ac051393278466f59bd2
+  data.tar.gz: 25de84d0345eb47d2c1866b0f7e6824278214aeac1e212adad3504d9682c70a8
 SHA512:
-  metadata.gz: 3a1910297ba003ca354ede4dd5312d12af4f6662d8cb0eca451f4f01e51ba54d80f3f27632785d2ba7c69d5504da042861d122c7a81356d19ca04046097928cd
-  data.tar.gz: 6d57ce3ec53d5ed22bfd91f284611c505400ad7f524f0fbfe0bec4fbf335e94fd4c91781248980342d127186c5973dfed9cd32011c2e6b2e1c6ea72531247f87
+  metadata.gz: 64ddc179ec70f82ebce87438daad5d50a199daee773fd453f7dff27b21c26af5f7a35fe96f7167405b5a24eb275af6e9519cbe53018194ad9388ae0e2c276412
+  data.tar.gz: a960d42269f80fedcd3c913ce7398a8c456759c07c58710533476f3648e38acde98921bdc93a4d26be8fa4405852d20ffbd0685802c114d87e5b9a6650941f59

data/Gemfile.lock

@@ -1,12 +1,26 @@
 PATH
   remote: .
   specs:
-    acidic_job (0.1.5)
+    acidic_job (0.2.0)
+      activerecord (>= 4.0.0)
       activesupport
 
 GEM
   remote: https://rubygems.org/
   specs:
+    actionpack (6.1.3.2)
+      actionview (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
+      rack (~> 2.0, >= 2.0.9)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actionview (6.1.3.2)
+      activesupport (= 6.1.3.2)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
     activejob (6.1.3.2)
       activesupport (= 6.1.3.2)
       globalid (>= 0.3.6)
@@ -22,7 +36,9 @@ GEM
       tzinfo (~> 2.0)
       zeitwerk (~> 2.3)
     ast (2.4.2)
+    builder (3.2.4)
     concurrent-ruby (1.1.9)
+    crass (1.0.6)
     database_cleaner (2.0.1)
       database_cleaner-active_record (~> 2.0.0)
     database_cleaner-active_record (2.0.1)
@@ -30,14 +46,40 @@ GEM
       database_cleaner-core (~> 2.0.0)
     database_cleaner-core (2.0.1)
     docile (1.4.0)
+    erubi (1.10.0)
     globalid (0.4.2)
       activesupport (>= 4.2.0)
     i18n (1.8.10)
       concurrent-ruby (~> 1.0)
+    loofah (2.12.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    method_source (1.0.0)
+    mini_portile2 (2.6.1)
     minitest (5.14.4)
+    nokogiri (1.12.3)
+      mini_portile2 (~> 2.6.1)
+      racc (~> 1.4)
+    nokogiri (1.12.3-x86_64-darwin)
+      racc (~> 1.4)
     parallel (1.20.1)
     parser (3.0.1.1)
       ast (~> 2.4.1)
+    racc (1.5.2)
+    rack (2.2.3)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.4.1)
+      loofah (~> 2.3)
+    railties (6.1.3.2)
+      actionpack (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
+      method_source
+      rake (>= 0.8.7)
+      thor (~> 1.0)
     rainbow (3.0.0)
     rake (13.0.4)
     regexp_parser (2.1.1)
@@ -65,6 +107,7 @@ GEM
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.3)
     sqlite3 (1.4.2)
+    thor (1.1.0)
     tzinfo (2.0.4)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.0.0)
@@ -80,6 +123,7 @@ DEPENDENCIES
   activerecord (~> 6.1.3.2)
   database_cleaner
   minitest (~> 5.0)
+  railties (>= 4.0)
   rake (~> 13.0)
   rubocop (~> 1.7)
   rubocop-minitest

data/README.md

@@ -2,7 +2,7 @@
 
 ### Idempotent operations for Rails apps, built on top of ActiveJob.
 
-At the conceptual heart of basically any software are "operations"—the discrete actions the software performs. Rails provides a powerful abstraction layer for building operations in the form of `ActiveJob`. With `ActiveJob`, we can easily trigger from other Ruby code throughout our Rails application (controller actions, model methods, model callbacks, etc.); we can run operations both synchronously (blocking execution and then returning its response to the caller) and asychronously (non-blocking and the caller doesn't know its response); and we can also retry a specific operation if needed seemlessly.
+At the conceptual heart of basically any software are "operations"—the discrete actions the software performs. Rails provides a powerful abstraction layer for building operations in the form of `ActiveJob`. With `ActiveJob`, we can easily trigger from other Ruby code throughout our Rails application (controller actions, model methods, model callbacks, etc.); we can run operations both synchronously (blocking execution and then returning its response to the caller) and asychronously (non-blocking and the caller doesn't know its response); and we can also retry a specific operation if needed seamlessly.
 
 However, in order to ensure that our operational jobs are _robust_, we need to ensure that they are properly [idempotent and transactional](https://github.com/mperham/sidekiq/wiki/Best-Practices#2-make-your-job-idempotent-and-transactional). As stated in the [GitLab Sidekiq Style Guide](https://docs.gitlab.com/ee/development/sidekiq_style_guide.html#idempotent-jobs):
 
@@ -19,7 +19,7 @@ This is, of course, far easier said than done. Thus, `AcidicJob`.
 3. https://brandur.org/job-drain
 4. https://brandur.org/idempotency-keys
 
-`AcididJob` brings these techniques and principles into the world of a standard Rails application.
+`AcidicJob` brings these techniques and principles into the world of a standard Rails application.
 
 ## Installation
 
@@ -40,7 +40,7 @@ Or install it yourself as:
 Then, use the following command to copy over the AcidicJobKey migration.
 
 ```
-rails generate acidic_job:key
+rails generate acidic_job
 ```
 
 ## Usage

data/acidic_job.gemspec

@@ -28,6 +28,8 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "activesupport"
+  spec.add_dependency "activerecord", ">= 4.0.0"
+  spec.add_development_dependency "railties", ">= 4.0"
 
   # For more information and examples about making a new gem, checkout our
   # guide at: https://bundler.io/guides/creating_gem.html

data/lib/acidic_job.rb

@@ -8,12 +8,6 @@ require "active_support/concern"
 
 # rubocop:disable Metrics/ModuleLength, Style/Documentation, Metrics/AbcSize, Metrics/MethodLength
 module AcidicJob
-  class IdempotencyKeyRequired < StandardError; end
-
-  class MissingRequiredAttribute < StandardError; end
-
-  class IdempotencyKeyTooShort < StandardError; end
-
   class MismatchedIdempotencyKeyAndJobArguments < StandardError; end
 
   class LockedIdempotencyKey < StandardError; end
@@ -38,31 +32,32 @@ module AcidicJob
   end
 
   # Number of seconds passed which we consider a held idempotency key lock to be
-  # defunct and eligible to be locked again by a different API call. We try to
+  # defunct and eligible to be locked again by a different job run. We try to
   # unlock keys on our various failure conditions, but software is buggy, and
   # this might not happen 100% of the time, so this is a hedge against it.
   IDEMPOTENCY_KEY_LOCK_TIMEOUT = 90
 
-  # To try and enforce some level of required randomness in an idempotency key,
-  # we require a minimum length. This of course is a poor approximate, and in
-  # real life you might want to consider trying to measure actual entropy with
-  # something like the Shannon entropy equation.
-  IDEMPOTENCY_KEY_MIN_LENGTH = 20
-
   # &block
-  def idempotently(with:)
+  def idempotently(with:) # &block
     # set accessors for each argument passed in to ensure they are available
     # to the step methods the job will have written
     define_accessors_for_passed_arguments(with)
 
     # execute the block to gather the info on what phases are defined for this job
     defined_steps = yield
+    # [:create_ride_and_audit_record, :create_stripe_charge, :send_receipt]
 
     # convert the array of steps into a hash of recovery_points and callable actions
     phases = define_atomic_phases(defined_steps)
+    # { create_ride_and_audit_record: <#Method >, ... }
 
-    # find or create an AcidicJobKey record to store all information about this job
+    # find or create an AcidicJobKey record (our idempotency key) to store all information about this job
     # side-effect: will set the @key instance variable
+    #
+    # A key concept here is that if two requests try to insert or update within
+    # close proximity, one of the two will be aborted by Postgres because we're
+    # using a transaction with SERIALIZABLE isolation level. It may not look
+    # it, but this code is safe from races.
     ensure_idempotency_key_record(job_id, with, defined_steps.first)
 
     # if the key record is already marked as finished, immediately return its result
@@ -74,7 +69,7 @@ module AcidicJob
       recovery_point = @key.recovery_point.to_sym
 
       case recovery_point
-      when :FINISHED
+      when AcidicJobKey::RECOVERY_POINT_FINISHED.to_sym
         break
       else
         raise UnknownRecoveryPoint unless phases.key? recovery_point
@@ -122,13 +117,12 @@ module AcidicJob
   end
 
   def ensure_idempotency_key_record(key_val, job_args, first_step)
-    # isolation_level = case ActiveRecord::Base.connection.adapter_name.downcase.to_sym
-    #                   when :sqlite
-    #                     :read_uncommitted
-    #                   else # :nocov:
-    #                     :serializable # :nocov:
-    #                   end
-    isolation_level = :read_uncommitted
+    isolation_level = case ActiveRecord::Base.connection.adapter_name.downcase.to_sym
+                      when :sqlite
+                        :read_uncommitted
+                      else
+                        :serializable
+                      end
 
     ActiveRecord::Base.transaction(isolation: isolation_level) do
       @key = AcidicJobKey.find_by(idempotency_key: key_val)
@@ -142,8 +136,7 @@ module AcidicJob
         # because the original job was long enough ago.
         raise LockedIdempotencyKey if @key.locked_at && @key.locked_at > Time.current - IDEMPOTENCY_KEY_LOCK_TIMEOUT
 
-        # Lock the key and update latest run unless the job is already
-        # finished.
+        # Lock the key and update latest run unless the job is already finished.
         @key.update!(last_run_at: Time.current, locked_at: Time.current) unless @key.finished?
       else
         @key = AcidicJobKey.create!(
@@ -170,14 +163,14 @@ module AcidicJob
   end
 
   def define_atomic_phases(defined_steps)
-    defined_steps << :FINISHED
+    defined_steps << AcidicJobKey::RECOVERY_POINT_FINISHED
 
     {}.tap do |phases|
       defined_steps.each_cons(2).map do |enter_method, exit_method|
         phases[enter_method] = lambda do
           method(enter_method).call
 
-          if exit_method == :FINISHED
+          if exit_method.to_s == AcidicJobKey::RECOVERY_POINT_FINISHED
             Response.new
           else
             RecoveryPoint.new(exit_method)

data/lib/acidic_job/no_op.rb

@@ -2,8 +2,10 @@
 
 # Represents an action to perform a no-op. One possible option for a return
 # from an #atomic_phase block.
-class NoOp
-  def call(_key)
-    # no-op
+module AcidicJob
+  class NoOp
+    def call(_key)
+      # no-op
+    end
   end
 end

data/lib/acidic_job/recovery_point.rb

@@ -2,14 +2,16 @@
 
 # Represents an action to set a new recovery point. One possible option for a
 # return from an #atomic_phase block.
-class RecoveryPoint
-  attr_accessor :name
+module AcidicJob
+  class RecoveryPoint
+    attr_accessor :name
 
-  def initialize(name)
-    self.name = name
-  end
+    def initialize(name)
+      self.name = name
+    end
 
-  def call(key:)
-    key.update(recovery_point: name)
+    def call(key:)
+      key.update_column(:recovery_point, name)
+    end
   end
 end

data/lib/acidic_job/response.rb

@@ -3,11 +3,13 @@
 # Represents an action to set a new API response (which will be stored onto an
 # idempotency key). One  possible option for a return from an #atomic_phase
 # block.
-class Response
-  def call(key:)
-    key.update!(
-      locked_at: nil,
-      recovery_point: :FINISHED
-    )
+module AcidicJob
+  class Response
+    def call(key:)
+      key.update!(
+        locked_at: nil,
+        recovery_point: AcidicJobKey::RECOVERY_POINT_FINISHED
+      )
+    end
   end
 end

data/lib/acidic_job/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AcidicJob
-  VERSION = "0.1.5"
+  VERSION = "0.2.0"
 end

data/lib/generators/acidic_job_generator.rb

@@ -0,0 +1,37 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+# This generator adds a migration for the {FriendlyId::History
+# FriendlyId::History} addon.
+class AcidicJobGenerator < ActiveRecord::Generators::Base
+  # ActiveRecord::Generators::Base inherits from Rails::Generators::NamedBase which requires a NAME parameter for the
+  # new table name. Our generator always uses 'acidic_job_keys', so we just set a random name here.
+  argument :name, type: :string, default: "random_name"
+
+  source_root File.expand_path("templates", __dir__)
+
+  def self.next_migration_number(_path)
+    if instance_variable_defined?("@prev_migration_nr")
+      @prev_migration_nr += 1
+    else
+      @prev_migration_nr = Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
+    end
+
+    @prev_migration_nr.to_s
+  end
+
+  # Copies the migration template to db/migrate.
+  def copy_files
+    migration_template "migration.rb",
+                       "db/migrate/create_acidid_job_keys.rb"
+  end
+
+  protected
+    def migration_class
+      if ActiveRecord::VERSION::MAJOR >= 5
+        ActiveRecord::Migration["#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}"]
+      else
+        ActiveRecord::Migration
+      end
+    end
+end

data/lib/generators/templates/migration.rb

@@ -0,0 +1,17 @@
+class CreateAcidicJobKeys < <%= migration_class %>
+  def change
+    create_table :acidic_job_keys do |t|
+      t.string :idempotency_key, null: false
+      t.string :job_name, null: false
+      t.text :job_args, null: false
+      t.datetime :last_run_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+      t.datetime :locked_at, null: true
+      t.string :recovery_point, null: false
+      t.text :error_object
+      t.timestamps
+
+      t.index %i[idempotency_key job_name job_args], unique: true,
+                                                     name: "idx_acidic_job_keys_on_idempotency_key_n_job_name_n_job_args"
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: acidic_job
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.2.0
 platform: ruby
 authors:
 - fractaledmind
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-07-09 00:00:00.000000000 Z
+date: 2021-08-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -24,6 +24,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
 description: Idempotent operations for Rails apps, built on top of ActiveJob.
 email:
 - stephen.margheim@gmail.com
@@ -48,6 +76,8 @@ files:
 - lib/acidic_job/recovery_point.rb
 - lib/acidic_job/response.rb
 - lib/acidic_job/version.rb
+- lib/generators/acidic_job_generator.rb
+- lib/generators/templates/migration.rb
 homepage: https://github.com/fractaledmind/acidic_job
 licenses:
 - MIT