acidic_job 0.1.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c51b3ed20bebb6322ab050f122c83d863fe16436e302b61f91eea84fd9cc117
-  data.tar.gz: 7f65a1d6c99d23930c4730557388833b3ebd277117394b18d6665978bf35119d
+  metadata.gz: 528d362023c8d2547054566f13d65556e057285124ffb05f8bc4c6007848b5cb
+  data.tar.gz: 05d08959ff8b674b48966ce4b879fd8c290d658a20c24b6af27e0c1fa8150452
 SHA512:
-  metadata.gz: 3a1910297ba003ca354ede4dd5312d12af4f6662d8cb0eca451f4f01e51ba54d80f3f27632785d2ba7c69d5504da042861d122c7a81356d19ca04046097928cd
-  data.tar.gz: 6d57ce3ec53d5ed22bfd91f284611c505400ad7f524f0fbfe0bec4fbf335e94fd4c91781248980342d127186c5973dfed9cd32011c2e6b2e1c6ea72531247f87
+  metadata.gz: 68bdc77c5e23e4fa680ca9ec72e00cf62cc1bcb2fc133b539d4c17f68b8926da9edd19f895ff92a0a379db567aee9ee949f0ade58eee0ef8b38edd61d28b5c19
+  data.tar.gz: b352b70b51cf7f3244a057dc5d6b2a89ede6e9b317346dd0fd0d54e9115ffff84a86670ac27c3bd45dc8b8f28d535de9af308fbd1b6be8dbd6eec76a7d740485

data/Gemfile

@@ -24,3 +24,5 @@ gem "sqlite3"
 gem "database_cleaner"
 
 gem "simplecov"
+
+gem "pry"

data/Gemfile.lock

@@ -1,12 +1,26 @@
 PATH
   remote: .
   specs:
-    acidic_job (0.1.5)
+    acidic_job (0.3.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,10 @@ GEM
       tzinfo (~> 2.0)
       zeitwerk (~> 2.3)
     ast (2.4.2)
+    builder (3.2.4)
+    coderay (1.1.3)
     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 +47,43 @@ 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)
+    pry (0.14.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    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 +111,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 +127,8 @@ DEPENDENCIES
   activerecord (~> 6.1.3.2)
   database_cleaner
   minitest (~> 5.0)
+  pry
+  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
 
@@ -33,14 +33,14 @@ And then execute:
 
     $ bundle install
 
-Or install it yourself as:
+Or simply execute to install the gem yourself:
 
-    $ gem install acidic_job
+    $ bundle add acidic_job
 
 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

@@ -3,15 +3,15 @@
 require_relative "lib/acidic_job/version"
 
 Gem::Specification.new do |spec|
-  spec.name          = "acidic_job"
-  spec.version       = AcidicJob::VERSION
-  spec.authors       = ["fractaledmind"]
-  spec.email         = ["stephen.margheim@gmail.com"]
+  spec.name = "acidic_job"
+  spec.version = AcidicJob::VERSION
+  spec.authors = ["fractaledmind"]
+  spec.email = ["stephen.margheim@gmail.com"]
 
-  spec.summary       = "Idempotent operations for Rails apps, built on top of ActiveJob."
-  spec.description   = "Idempotent operations for Rails apps, built on top of ActiveJob."
-  spec.homepage      = "https://github.com/fractaledmind/acidic_job"
-  spec.license       = "MIT"
+  spec.summary = "Idempotent operations for Rails apps, built on top of ActiveJob."
+  spec.description = "Idempotent operations for Rails apps, built on top of ActiveJob."
+  spec.homepage = "https://github.com/fractaledmind/acidic_job"
+  spec.license = "MIT"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.7.0")
 
   spec.metadata["homepage_uri"] = spec.homepage
@@ -23,11 +23,13 @@ Gem::Specification.new do |spec|
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
   end
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   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/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: Key::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.3.0"
 end

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
@@ -24,6 +18,33 @@ module AcidicJob
 
   class SerializedTransactionConflict < StandardError; end
 
+  class Key < ActiveRecord::Base
+    RECOVERY_POINT_FINISHED = "FINISHED"
+
+    self.table_name = "acidic_job_keys"
+
+    serialize :error_object
+    serialize :job_args
+
+    validates :idempotency_key, presence: true, uniqueness: {scope: [:job_name, :job_args]}
+    validates :job_name, presence: true
+    validates :job_args, presence: true
+    validates :last_run_at, presence: true
+    validates :recovery_point, presence: true
+
+    def finished?
+      recovery_point == RECOVERY_POINT_FINISHED
+    end
+
+    def succeeded?
+      finished? && !failed?
+    end
+
+    def failed?
+      error_object.present?
+    end
+  end
+
   extend ActiveSupport::Concern
 
   included do
@@ -38,32 +59,33 @@ 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 Key record (our idempotency key) to store all information about this job
     # side-effect: will set the @key instance variable
-    ensure_idempotency_key_record(job_id, with, defined_steps.first)
+    #
+    # 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, defined_steps.first)
 
     # if the key record is already marked as finished, immediately return its result
     return @key.succeeded? if @key.finished?
@@ -74,7 +96,7 @@ module AcidicJob
       recovery_point = @key.recovery_point.to_sym
 
       case recovery_point
-      when :FINISHED
+      when Key::RECOVERY_POINT_FINISHED.to_sym
         break
       else
         raise UnknownRecoveryPoint unless phases.key? recovery_point
@@ -105,7 +127,7 @@ module AcidicJob
 
         phase_result.call(key: key)
       end
-    rescue StandardError => e
+    rescue => e
       error = e
       raise e
     ensure
@@ -113,7 +135,7 @@ module AcidicJob
       # key right away so that another request can try again.
       begin
         key.update_columns(locked_at: nil, error_object: error) if error.present?
-      rescue StandardError => e
+      rescue => e
         # We're already inside an error condition, so swallow any additional
         # errors from here and just send them to logs.
         puts "Failed to unlock key #{key.id} because of #{e}."
@@ -121,38 +143,37 @@ module AcidicJob
     end
   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
+  def ensure_idempotency_key_record(key_val, first_step)
+    isolation_level = case ActiveRecord::Base.connection.adapter_name.downcase.to_sym
+                      when :sqlite
+                        :read_uncommitted
+                      else
+                        :serializable
+    end
+    serialized_job_info = serialize
 
     ActiveRecord::Base.transaction(isolation: isolation_level) do
-      @key = AcidicJobKey.find_by(idempotency_key: key_val)
+      @key = Key.find_by(idempotency_key: key_val)
 
       if @key
         # Programs enqueuing multiple jobs with different parameters but the
         # same idempotency key is a bug.
-        raise MismatchedIdempotencyKeyAndJobArguments if @key.job_args != job_args.as_json
+        raise MismatchedIdempotencyKeyAndJobArguments if @key.job_args != serialized_job_info["arguments"]
 
         # Only acquire a lock if the key is unlocked or its lock has expired
         # 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!(
+        @key = Key.create!(
           idempotency_key: key_val,
           locked_at: Time.current,
           last_run_at: Time.current,
           recovery_point: first_step,
-          job_name: self.class.name,
-          job_args: job_args.as_json
+          job_name: serialized_job_info["job_class"],
+          job_args: serialized_job_info["arguments"]
         )
       end
     end
@@ -170,14 +191,14 @@ module AcidicJob
   end
 
   def define_atomic_phases(defined_steps)
-    defined_steps << :FINISHED
+    defined_steps << Key::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 == Key::RECOVERY_POINT_FINISHED
             Response.new
           else
             RecoveryPoint.new(exit_method)

data/lib/generators/acidic_job_generator.rb

@@ -0,0 +1,38 @@
+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_acidic_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,18 @@
+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.3.0
 platform: ruby
 authors:
 - fractaledmind
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-07-09 00:00:00.000000000 Z
+date: 2021-08-25 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