acidic_job 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34c65a77db46e2a7e38aaee61428a0739027820a7a796edf42b91e864818af22
-  data.tar.gz: cd0cfaa3efe9244fc82ea32f197099c29dff0326534a44411e73569158396759
+  metadata.gz: 9878e2b82544c04809b49366f27eafcbe28683c39ca877fb99b9649c4bd4dcdd
+  data.tar.gz: b04206a126a00f84caeb255a6a3bb6542001a6a700345edfd45fe68d39b3fcdd
 SHA512:
-  metadata.gz: 20158e851d244eaa05881e0ca3723397f4e48cc5b17537956f114bf5507831e9e2ddb17ffb9fa35496a50c067539dc3aa5fb4a9051dd61da71dab0e9e04c1833
-  data.tar.gz: 52272d8d404339ecd6442118e5a5c6718febc9688905dece63bda85d9837d43edbbdfe7386284abcd773660c6b95b98b8caeb7ae6af83267ed2f6778ed952d21
+  metadata.gz: 7d7928c276825f884387a6010cf57e1fc2b04f17e657c230c5d6909e8430445dfb903018643812255100ac8fdbf7dfe20fae0f5d194089aa003c7f6b4c996830
+  data.tar.gz: befa1e96050d612cb42fff983b751f8f04dada4f5ccd5ac81ba0190807f69e6961d1a19bdb6df06bce0e2252c60bac5dd0a37c202afa5c1f03942d46ff469828

data/acidic_job.gemspec

@@ -27,8 +27,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  # Uncomment to register a new dependency of your gem
-  # spec.add_dependency "example-gem", "~> 1.0"
+  spec.add_dependency 'activesupport'
 
   # 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

@@ -1,8 +1,221 @@
 # frozen_string_literal: true
 
 require_relative "acidic_job/version"
+require_relative "acidic_job/no_op"
+require_relative "acidic_job/recovery_point"
+require_relative "acidic_job/response"
 
 module AcidicJob
-  class Error < StandardError; end
-  # Your code goes here...
+  class IdempotencyKeyRequired < StandardError; end
+
+  class MissingRequiredAttribute < StandardError; end
+
+  class IdempotencyKeyTooShort < StandardError; end
+
+  class MismatchedIdempotencyKeyAndJobArguments < StandardError; end
+
+  class LockedIdempotencyKey < StandardError; end
+
+  class UnknownRecoveryPoint < StandardError; end
+
+  class UnknownAtomicPhaseType < StandardError; end
+
+  class SerializedTransactionConflict < StandardError; end
+
+  extend ActiveSupport::Concern
+
+  included do
+    attr_reader :key
+  end
+
+  class_methods do
+    def required(*names)
+      required_attributes.push(*names)
+    end
+
+    def required_attributes
+      return @required_attributes if instance_variable_defined?(:@required_attributes)
+
+      @required_attributes = []
+    end
+  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
+  # 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
+
+  def idempotently(key:, with:) # &block
+    # set accessors for each argument passed in to ensure they are available
+    # to the step methods the job will have written
+    set_accessors_for_passed_arguments(with)
+
+    validate_passed_idempotency_key(key)
+    validate_passed_arguments(with)
+
+    # execute the block to gather the info on what phases are defined for this job
+    defined_steps = yield
+
+    # convert the array of steps into a hash of recovery_points and callable actions
+    phases = define_atomic_phases(defined_steps)
+
+    # find or create an AcidicJobKey record to store all information about this job
+    # side-effect: will set the @key instance variable
+    ensure_idempotency_key_record(key, params, defined_steps.first)
+
+    # if the key record is already marked as finished, immediately return its result
+    return @key.succeeded? if @key.finished?
+
+    # otherwise, we will enter a loop to process each required step of the job
+    100.times do
+      # our `phases` hash uses Symbols for keys
+      recovery_point = @key.recovery_point.to_sym
+
+      case recovery_point
+      when :FINISHED
+        break
+      else
+        raise UnknownRecoveryPoint unless phases.key? recovery_point
+
+        atomic_phase @key, phases[recovery_point]
+      end
+    end
+
+    # the loop will break once the job is finished, so simply report the status
+    @key.succeeded?
+  end
+
+  def step(method_name)
+    @_steps ||= []
+    @_steps << method_name
+    @_steps
+  end
+
+  private
+
+  def atomic_phase(key = nil, proc = nil, &block)
+    error = false
+    phase_callable = (proc || block)
+
+    begin
+      # ActiveRecord::Base.transaction(isolation: :serializable) do
+      ActiveRecord::Base.transaction(isolation: :read_uncommitted) do
+        phase_result = phase_callable.call
+
+        if phase_result.is_a?(NoOp) || phase_result.is_a?(RecoveryPoint) || phase_result.is_a?(Response)
+          key ||= @key
+          phase_result.call(key: key)
+        else
+          raise UnknownAtomicPhaseType
+        end
+      end
+    rescue MismatchedIdempotencyKeyAndJobArguments, LockedIdempotencyKey, UnknownRecoveryPoint, UnknownAtomicPhaseType, MissingRequiredAttribute, ActiveRecord::SerializationFailure => e
+      error = e
+      raise e
+    rescue => e
+      error = e
+      raise e
+    ensure
+      # If we're leaving under an error condition, try to unlock the idempotency
+      # key right away so that another request can try again.
+      if error && !key.nil?
+        begin
+          key.update(locked_at: nil, error_object: error)
+        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}."
+        end
+      end
+    end
+  end
+
+  def ensure_idempotency_key_record(key_val, params, first_step)
+    atomic_phase do
+      @key = AcidicJobKey.find_by(idempotency_key: key_val)
+
+      if @key
+        # Programs enqueuing multiple jobs with different parameters but the
+        # same idempotency key is a bug.
+        if @key.job_args != params.as_json
+          raise MismatchedIdempotencyKeyAndJobArguments
+        end
+
+        # Only acquire a lock if the key is unlocked or its lock has expired
+        # because the original job was long enough ago.
+        if @key.locked_at && @key.locked_at > Time.current - IDEMPOTENCY_KEY_LOCK_TIMEOUT
+          raise LockedIdempotencyKey
+        end
+
+        # Lock the key and update latest run unless the job is already
+        # finished.
+        if !@key.finished?
+          @key.update!(last_run_at: Time.current, locked_at: Time.current)
+        end
+      else
+        @key = AcidicJobKey.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: params.as_json
+        )
+      end
+
+      # no response and no need to set a recovery point
+      NoOp.new
+    end
+  end
+
+  def set_accessors_for_passed_arguments(passed_arguments)
+    passed_arguments.each do |accessor, value|
+      self.class.attr_accessor accessor
+      instance_variable_set("@#{accessor}", value)
+    end
+
+    true
+  end
+
+  def validate_passed_idempotency_key(key)
+    raise IdempotencyKeyRequired if key.nil?
+    raise IdempotencyKeyTooShort if key.length < IDEMPOTENCY_KEY_MIN_LENGTH
+
+    true
+  end
+
+  def validate_passed_arguments(attributes)
+    missing_attributes = self.class.required_attributes.select do |required_attribute|
+      attributes[required_attribute].nil?
+    end
+
+    return if missing_attributes.empty?
+
+    raise MissingRequiredAttribute, "The following required job parameters are missing: #{missing_attributes.to_sentence}"
+  end
+
+  def define_atomic_phases(defined_steps)
+    defined_steps << :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
+            Response.new
+          else
+            RecoveryPoint.new(exit_method)
+          end
+        end
+      end
+    end
+  end
 end

data/lib/acidic_job/no_op.rb

@@ -0,0 +1,7 @@
+# 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
+  end
+end

data/lib/acidic_job/recovery_point.rb

@@ -0,0 +1,13 @@
+# 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
+
+  def initialize(name)
+    self.name = name
+  end
+
+  def call(key:)
+    key.update(recovery_point: name)
+  end
+end

data/lib/acidic_job/response.rb

@@ -0,0 +1,11 @@
+# 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
+    )
+  end
+end

data/lib/acidic_job/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: acidic_job
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - fractaledmind
@@ -9,7 +9,21 @@ autorequire:
 bindir: exe
 cert_chain: []
 date: 2021-06-20 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Idempotent operations for Rails apps, built on top of ActiveJob.
 email:
 - stephen.margheim@gmail.com
@@ -29,6 +43,9 @@ files:
 - bin/console
 - bin/setup
 - lib/acidic_job.rb
+- lib/acidic_job/no_op.rb
+- lib/acidic_job/recovery_point.rb
+- lib/acidic_job/response.rb
 - lib/acidic_job/version.rb
 homepage: https://github.com/fractaledmind/acidic_job
 licenses: