stepper_motor 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0bf607219c84d08a1a2f523a8bfdb2f65735ef947b9d18df6079f8b3154ffce5
-  data.tar.gz: e75a98bbdc4e87eb2d7053cd045dcd97733fa3d748e5db7193c41f9d10042183
+  metadata.gz: a959b0f7b493cb88f9a89f1d84e7d5e9d9c968ac3f4025b31ed9d62e516f71df
+  data.tar.gz: 3ebfef286a7e80cad55478631f583e4d21f5ee153d05a2ef99ef4863bc6755c2
 SHA512:
-  metadata.gz: 66dbb65657298caab318a6feae9ce01c402f61f56f95d26b12e82f803c71f8dc12dcca4c18475ab91782f1082cedcffe7a48ffef89ce9d14c7c4ee114afb8b2e
-  data.tar.gz: 2dbcefac4833a846fc0abd0dda9cdfc1c4ef6212f6d7e94ee887548e57ed3d5aeb8bdb9ff0ac71803ec3b0db88b5df1ea4dd34c8b19c733d200ebd4ae4d9b2ed
+  metadata.gz: b43d2817735016bcaec60af188e405ccd67c5f86f09de4c43993b84a38a80e73f1a8c3be198a5c34d9e31b0f9e02b6397463a4307157dbba577f23ef87935787
+  data.tar.gz: 9403ad567b33918bfbe89da14ae9641fd2be5db621bdc78ecda18e84be12159a391eafe51c76b22d5711897d2ab17b3de6aafbe8751b9904e65aae66fb7e9b86

data/.standard.yml

@@ -1,8 +1,4 @@
 ruby_version: 3.1
 ignore:
-  - 'spec/**/*':
-    - Lint/ConstantDefinitionInBlock
-    - Style/GlobalVars
-  - 'lib/zip_kit/rack_body.rb': # Erroneous detection
-    - Lint/OrderedMagicComments
-    - Layout/EmptyLineAfterMagicComment
+  - 'spec/app/db/**/*':
+    - Layout/TrailingWhitespace # Templated migrations have whitespace

data/Rakefile

@@ -2,9 +2,12 @@
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
 require "standard/rake"
 
+task :format do
+  `bundle exec standardrb --fix`
+  `bundle exec magic_frozen_string_literal .`
+end
+
+RSpec::Core::RakeTask.new(:spec)
 task default: %i[spec standard]

data/lib/generators/stepper_motor_migration_002.rb.erb

@@ -0,0 +1,6 @@
+class StepperMotorMigration002 < ActiveRecord::Migration[<%= migration_version %>]
+  def change
+    # An index is needed to recover stuck journeys
+    add_index :stepper_motor_journeys, [:updated_at], name: "stuck_journeys_index", where: "state = 'performing'"
+  end
+end

data/lib/stepper_motor/cyclic_scheduler.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # The cyclic scheduler is designed to be run regularly via a cron job. On every
 # cycle, it is going to look for Journeys which are going to come up for step execution
 # before the next cycle is supposed to run. Then it is going to enqueue jobs to perform

data/lib/stepper_motor/forward_scheduler.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # The forward scheduler enqueues a job for every Journey that
 # gets sent to the `#schedule`. The job is then stored in the queue
 # and gets picked up by the ActiveJob worker normally. This is the simplest
@@ -13,6 +15,8 @@
 # this scheduler is not a good fit for you, and you will need to use the {CyclicScheduler} instead.
 class StepperMotor::ForwardScheduler
   def schedule(journey)
-    StepperMotor::PerformStepJob.set(wait_until: journey.next_step_to_be_performed_at).perform_later(journey.to_global_id.to_s)
+    StepperMotor::PerformStepJobV2
+      .set(wait_until: journey.next_step_to_be_performed_at)
+      .perform_later(journey_id: journey.id, journey_class_name: journey.class.to_s)
   end
 end

data/lib/stepper_motor/journey.rb

@@ -52,6 +52,33 @@ module StepperMotor
       where(hero: hero)
     }
 
+    # Allows querying for Journeys which are stuck in "performing" state since a certain
+    # timestamp. These Journeys have likely been stuck because the worker that was performing
+    # the step has crashed or was forcibly restarted.
+    scope :stuck, ->(since) {
+      where(updated_at: ..since).performing
+    }
+
+    # Sets the behavior when a Journey gets stuck in "performing" state. The default us "reattempt" -
+    # it is going to try to restart the step the Journey got stuck on
+    class_attribute :when_stuck, default: :reattempt, instance_accessor: false, instance_reader: true
+
+    def recover!
+      case when_stuck
+      when :reattempt
+        with_lock do
+          return unless performing?
+          ready!
+          schedule!
+        end
+      else
+        with_lock do
+          return unless performing?
+          canceled!
+        end
+      end
+    end
+
     after_create do |journey|
       journey.step_definitions.any? ? journey.set_next_step_and_enqueue(journey.step_definitions.first) : journey.finished!
     end

data/lib/stepper_motor/perform_step_job.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "active_job"
 
 class StepperMotor::PerformStepJob < ActiveJob::Base

data/lib/stepper_motor/perform_step_job_v2.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+class StepperMotor::PerformStepJobV2 < ActiveJob::Base
+  def perform(journey_id:, journey_class_name:, **)
+    journey = StepperMotor::Journey.find(journey_id)
+    journey.perform_next_step!
+  rescue ActiveRecord::RecordNotFound
+    # The journey has been canceled and destroyed previously or elsewhere
+  end
+end

data/lib/stepper_motor/{reap_hung_journeys_job.rb → recover_stuck_journeys_job_v1.rb}

@@ -1,12 +1,17 @@
+# frozen_string_literal: true
+
+require "active_job"
+
 # The purpose of this job is to find journeys which have, for whatever reason, remained in the
 # `performing` state for far longer than the journey is supposed to. At the moment it assumes
 # any journey that stayed in `performing` for longer than 1 hour has hung. Add this job to your
 # cron table and perform it regularly.
-class StepperMotor::ReapHungJourneysJob < ActiveJob::Base
-  def perform
-    StepperMotor::Journey.where("state = 'performing' AND updated_at < ?", 1.hour.ago).find_each do |hung_journey|
-      hung_journey.update!(state: "ready")
-      StepperMotor.scheduler.schedule(hung_journey)
+class StepperMotor::RecoverStuckJourneysJobV1 < ActiveJob::Base
+  def perform(stuck_for: 2.days)
+    StepperMotor::Journey.stuck(stuck_for.ago).find_each do |journey|
+      journey.recover!
+    rescue => e
+      Rails&.error&.report(e)
     end
   end
 end

data/lib/stepper_motor/step.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Describes a step in a journey. These objects get stored inside the `step_definitions`
 # array of the Journey subclass. When the step gets performed, the block passed to the
 # constructor will be instance_exec'd with the Journey model being the context

data/lib/stepper_motor/test_helper.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module StepperMotor::TestHelper
   # Allows running a given Journey to completion, skipping across the waiting periods.
   # This is useful to evaluate all side effects of a Journey. The helper will ensure

data/lib/stepper_motor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StepperMotor
-  VERSION = "0.1.4"
+  VERSION = "0.1.6"
 end

data/lib/stepper_motor.rb

@@ -13,6 +13,8 @@ module StepperMotor
   autoload :Journey, File.dirname(__FILE__) + "/stepper_motor/journey.rb"
   autoload :Step, File.dirname(__FILE__) + "/stepper_motor/step.rb"
   autoload :PerformStepJob, File.dirname(__FILE__) + "/stepper_motor/perform_step_job.rb"
+  autoload :PerformStepJobV2, File.dirname(__FILE__) + "/stepper_motor/perform_step_job_v2.rb"
+  autoload :RecoverStuckJourneysJobV1, File.dirname(__FILE__) + "/stepper_motor/recover_stuck_journeys_job_v1.rb"
   autoload :InstallGenerator, File.dirname(__FILE__) + "/generators/install_generator.rb"
   autoload :ForwardScheduler, File.dirname(__FILE__) + "/stepper_motor/forward_scheduler.rb"
   autoload :CyclicScheduler, File.dirname(__FILE__) + "/stepper_motor/cyclic_scheduler.rb"

data/spec/helpers/side_effects.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module SideEffects
   module SpecHelper
     def self.included(into)

data/spec/spec_helper.rb

@@ -56,7 +56,7 @@ end
 module JourneyDefinitionHelper
   def create_journey_subclass(&blk)
     # https://stackoverflow.com/questions/4113479/dynamic-class-definition-with-a-class-name
-    random_component = Random.hex(8)
+    random_component = Random.hex(2)
     random_name = "JourneySubclass#{random_component}"
     klass = Class.new(StepperMotor::Journey, &blk)
     Object.const_set(random_name, klass)
@@ -85,5 +85,6 @@ RSpec.configure do |config|
     StepperMotorRailtieTestHelpers.establish_test_connection
     StepperMotorRailtieTestHelpers.run_generator
     StepperMotorRailtieTestHelpers.run_migrations
+    ActiveJob::Base.logger.level = Logger::FATAL
   end
 end

data/spec/stepper_motor/cyclic_scheduler_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "../spec_helper"
 
 RSpec.describe "StepperMotor::CyclicScheduler" do

data/spec/stepper_motor/forward_scheduler_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "../spec_helper"
 
 RSpec.describe "StepperMotor::ForwardScheduler" do
@@ -30,7 +32,7 @@ RSpec.describe "StepperMotor::ForwardScheduler" do
     expect(enqueued_jobs.size).to eq(1)
     job = enqueued_jobs.first
 
-    expect(job["job_class"]).to eq("StepperMotor::PerformStepJob")
+    expect(job["job_class"]).to eq("StepperMotor::PerformStepJobV2")
     expect(job["scheduled_at"]).not_to be_nil
 
     scheduled_at = Time.parse(job["scheduled_at"])

data/spec/stepper_motor/generator_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "../spec_helper"
 
 RSpec.describe "StepperMotor::InstallGenerator" do

data/spec/stepper_motor/journey_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "../spec_helper"
 
 # rubocop:disable Lint/ConstantDefinitionInBlock
@@ -26,8 +28,6 @@ RSpec.describe "StepperMotor::Journey" do
   end
 
   it "allows a journey consisting of multiple named steps to be defined and performed to completion" do
-    step_names = [:step1, :step2, :step3]
-
     multi_step_journey_class = create_journey_subclass do
       [:step1, :step2, :step3].each do |step_name|
         step step_name do
@@ -103,7 +103,7 @@ RSpec.describe "StepperMotor::Journey" do
   end
 
   it "allows a journey where steps are delayed in time using wait:" do
-    timely_journey_class = carrier_journey_class = create_journey_subclass do
+    timely_journey_class = create_journey_subclass do
       step wait: 10.hours do
         SideEffects.touch! "after_10_hours.txt"
       end

data/spec/stepper_motor/recover_stuck_journeys_job_spec.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "../spec_helper"
+
+RSpec.describe "RecoveryStuckJourneysJobV1" do
+  before do
+    StepperMotor::Journey.delete_all
+  end
+
+  it "handles recovery from a background job" do
+    stuck_journey_class1 = create_journey_subclass do
+      self.when_stuck = :cancel
+
+      step :first do
+      end
+
+      step :second, wait: 4.days do
+        Fiber.yield # Simulate the journey hanging
+      end
+    end
+
+    stuck_journey_class2 = create_journey_subclass do
+      self.when_stuck = :reattempt
+
+      step :first do
+      end
+
+      step :second, wait: 4.days do
+        Fiber.yield # Simulate the journey hanging
+      end
+    end
+
+    freeze_time
+
+    journey_to_cancel = stuck_journey_class1.create!
+    journey_to_reattempt = stuck_journey_class2.create!
+
+    journey_to_cancel.perform_next_step!
+    journey_to_reattempt.perform_next_step!
+
+    travel_to Time.now + 5.days
+
+    # Get both stuck
+    Fiber.new do
+      journey_to_cancel.perform_next_step!
+    end.resume
+
+    Fiber.new do
+      journey_to_reattempt.perform_next_step!
+    end.resume
+
+    expect(journey_to_cancel.reload).to be_performing
+    expect(journey_to_reattempt.reload).to be_performing
+
+    StepperMotor::RecoverStuckJourneysJobV1.perform_now(stuck_for: 2.days)
+    expect(journey_to_cancel.reload).to be_performing
+    expect(journey_to_reattempt.reload).to be_performing
+
+    travel_to Time.now + 2.days + 1.second
+    StepperMotor::RecoverStuckJourneysJobV1.perform_now(stuck_for: 2.days)
+
+    expect(journey_to_cancel.reload).to be_canceled
+    expect(journey_to_reattempt.reload).to be_ready
+  end
+
+  it "does not raise when the class of the journey is no longer present" do
+    stuck_journey_class1 = create_journey_subclass do
+      self.when_stuck = :cancel
+
+      step :first do
+        Fiber.yield # Simulate the journey hanging
+      end
+    end
+
+    freeze_time
+
+    journey_to_cancel = stuck_journey_class1.create!
+    Fiber.new do
+      journey_to_cancel.perform_next_step!
+    end.resume
+    expect(journey_to_cancel.reload).to be_performing
+
+    journey_to_cancel.class.update_all(type: "UnknownJourneySubclass")
+
+    expect {
+      StepperMotor::RecoverStuckJourneysJobV1.perform_now(stuck_for: 2.days)
+    }.not_to raise_error
+  end
+end

data/spec/stepper_motor/recovery_spec.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative "../spec_helper"
+
+RSpec.describe "Recovery of stuck journeys" do
+  before do
+    StepperMotor::Journey.delete_all
+  end
+
+  it "recovers a journey by reattempting it" do
+    stuck_journey_class = create_journey_subclass do
+      step :first do
+      end
+
+      step :second, wait: 4.days do
+        Fiber.yield # Simulate the journey hanging
+      end
+
+      step :third, wait: 4.days do
+      end
+    end
+
+    freeze_time
+    journey = stuck_journey_class.create!
+
+    journey.perform_next_step!
+    expect(journey.next_step_name).to eq("second")
+
+    travel_to Time.now + 5.days
+
+    expect(stuck_journey_class.when_stuck).to eq(:reattempt)
+    expect(journey.when_stuck).to eq(:reattempt)
+
+    # Hang the journey in "performing"
+    stuck_fiber = Fiber.new do
+      journey.perform_next_step!
+    end
+    stuck_fiber.resume
+
+    expect(journey).to be_persisted
+    expect(journey).to be_performing
+    expect(journey.updated_at).to eq(Time.now)
+
+    expect(StepperMotor::Journey.stuck(1.days.ago)).not_to include(journey)
+
+    travel_to Time.now + 2.days
+    expect(StepperMotor::Journey.stuck(2.days.ago)).to include(journey)
+
+    perform_at_before_recovery = journey.next_step_to_be_performed_at
+    expect {
+      journey.reload.recover!
+    }.not_to raise_error
+
+    journey.reload
+    expect(journey.next_step_to_be_performed_at).to eq(perform_at_before_recovery)
+    expect(journey.next_step_name).to eq("second")
+  end
+
+  it "recovers a journey by canceling it" do
+    stuck_journey_class = create_journey_subclass do
+      self.when_stuck = :cancel
+
+      step :first do
+      end
+
+      step :second, wait: 4.days do
+        Fiber.yield # Simulate the journey hanging
+      end
+
+      step :third, wait: 4.days do
+      end
+    end
+
+    freeze_time
+    journey = stuck_journey_class.create!
+
+    journey.perform_next_step!
+    expect(journey.next_step_name).to eq("second")
+
+    travel_to Time.now + 5.days
+
+    expect(stuck_journey_class.when_stuck).to eq(:cancel)
+    expect(journey.when_stuck).to eq(:cancel)
+
+    # Hang the journey in "performing"
+    stuck_fiber = Fiber.new do
+      journey.perform_next_step!
+    end
+    stuck_fiber.resume
+
+    expect(journey).to be_persisted
+    expect(journey).to be_performing
+    expect(journey.updated_at).to eq(Time.now)
+
+    travel_to Time.now + 2.days
+    expect(StepperMotor::Journey.stuck(2.days.ago)).to include(journey)
+
+    expect {
+      journey.reload.recover!
+    }.not_to raise_error
+
+    journey.reload
+    expect(journey).to be_canceled
+  end
+end

data/spec/stepper_motor/test_helper_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "../spec_helper"
 
 RSpec.describe "StepperMotor::TestHelper" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stepper_motor
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - Julik Tarkhanov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-11 00:00:00.000000000 Z
+date: 2025-05-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -136,6 +136,20 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 1.28.5
+- !ruby/object:Gem::Dependency
+  name: magic_frozen_string_literal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -183,13 +197,15 @@ files:
 - bin/setup
 - lib/generators/install_generator.rb
 - lib/generators/stepper_motor_migration_001.rb.erb
+- lib/generators/stepper_motor_migration_002.rb.erb
 - lib/stepper_motor.rb
 - lib/stepper_motor/cyclic_scheduler.rb
 - lib/stepper_motor/forward_scheduler.rb
 - lib/stepper_motor/journey.rb
 - lib/stepper_motor/perform_step_job.rb
+- lib/stepper_motor/perform_step_job_v2.rb
 - lib/stepper_motor/railtie.rb
-- lib/stepper_motor/reap_hung_journeys_job.rb
+- lib/stepper_motor/recover_stuck_journeys_job_v1.rb
 - lib/stepper_motor/step.rb
 - lib/stepper_motor/test_helper.rb
 - lib/stepper_motor/version.rb
@@ -200,6 +216,8 @@ files:
 - spec/stepper_motor/forward_scheduler_spec.rb
 - spec/stepper_motor/generator_spec.rb
 - spec/stepper_motor/journey_spec.rb
+- spec/stepper_motor/recover_stuck_journeys_job_spec.rb
+- spec/stepper_motor/recovery_spec.rb
 - spec/stepper_motor/test_helper_spec.rb
 - spec/stepper_motor_spec.rb
 homepage: https://steppermotor.dev