stepper_motor 0.1.9 → 0.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da2327efc5b8425041ad9cf331bb450dfd81049ac767daab8f8b445d0c518c53
-  data.tar.gz: 02305e571a142384e3dce303c64637fa44029a14ca9ca5770f369b5c7c707ab2
+  metadata.gz: 619a3e8a9435e06f7fcf5b61ddc41d7ebb62450cb9fafccf89f8399818264ef0
+  data.tar.gz: 3c3009f6b5c48a8dcdcd92187dbadc21d92c37b86746b8426dba8b6b60cb007f
 SHA512:
-  metadata.gz: ecb7dfe9e36759bf2b789d364fcc46399778487f352a634ac73822698b822b4ca1556818da958a480404f9710381e40a96a53310d65f2c77ba90b84ebd2664f7
-  data.tar.gz: a8a7d73d008e2bf5286446e8aeb709310a2a475066c6101101131adf5346ca966ae45e8f0c38d98822771e1310b0de160284409b188fa98b5e0787fec2a6b865
+  metadata.gz: 1911106735b7ef6d54e7b3149cfbf26a13a6a0ec8e69a45429e244216c32f46b63b114b8101b369a36c22cdae10682a8c0adf599f18efe9bcfd2a9ded05be3ab
+  data.tar.gz: e9996b145db211444300230ae742e8da61f8db21f3841a21c97a37779203767f4fc46535656c698c494001bbe024c6cd681599595df5a73fdaae101417ebde4c

data/CHANGELOG.md

@@ -1,16 +1,30 @@
 # Changelog
 
+## [0.1.11] - 2025-06-08
+
+- Add automatic cleanup of completed journeys after a configurable time period
+- Add `HousekeepingJob` to run cleanup and recovery tasks
+- Add ability to extend all StepperMotor jobs with custom configuration
+- Merge V2/V1 job variants into single classes with backward compatibility
+- Pin standardrb version to avoid Rubocop errors
+- Improve documentation and test coverage
+
+## [0.1.10] - 2025-05-28
+
+- Remove `algorithm: :concurrently` from migrations. If a user needs to conform with strong_migrations
+  they can always edit the migration themselves.
+
 ## [0.1.9] - 2025-05-25
 
 - Repair bodged migration from the previous release
 
 ## [0.1.8] - 2025-05-25
 
-- Add ability to pause and resume journeys (#24)
-- Add basic exception rescue during steps (#23)
-- Add idempotency keys when performing steps (#21)
-- Add support for blockless step definitions (#22)
-- Migrate from RSpec to Minitest (#19)
+- Add ability to pause and resume journeys (https://github.com/stepper-motor/stepper_motor/pull/24)
+- Add basic exception rescue during steps (https://github.com/stepper-motor/stepper_motor/pull/23)
+- Add idempotency keys when performing steps (https://github.com/stepper-motor/stepper_motor/pull/21)
+- Add support for blockless step definitions (https://github.com/stepper-motor/stepper_motor/pull/22)
+- Migrate from RSpec to Minitest (https://github.com/stepper-motor/stepper_motor/pull/19)
 - Add Rake task for recovery
 - Add proper Rails engine tests
 - Improve test organization and coverage
@@ -41,7 +55,6 @@
 - Refactor PerformStepJob to use Journey class in job arguments
 - Remove GlobalID dependency
 - Add ability to resolve Journey from base class using `find()`
-- Prepare groundwork for future improvements (#12)
 
 ## [0.1.4] - 2025-03-11
 

data/README.md

@@ -24,7 +24,7 @@ end
 SignupJourney.create!(hero: current_user)
 ```
 
-Want to know more? Dive into the [manual](file.MANUAL.html) we provide.
+Want to know more? Dive into the [manual](/manual/MANUAL.md) we provide.
 
 ## Installation
 
@@ -47,9 +47,7 @@ Starting with versions 0.2.x and up, stepper_motor will make the best possible e
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+After checking out the repo, run `bundle` to install dependencies. The development process from there on is like any other gem.
 
 ## Is it any good?
 

data/lib/generators/install_generator.rb

@@ -9,8 +9,8 @@ module StepperMotor
   # Run it with `bin/rails g stepper_motor:install` in your console.
   class InstallGenerator < Rails::Generators::Base
     UUID_MESSAGE = <<~MSG
-      If set, uuid type will be used for hero_id. Use this
-      if most of your models use UUD as primary key"
+      If set, uuid type will be used for hero_id of the Journeys, as well as for the Journey IDs.
+      Use this if most of your models use UUD as primary key"
     MSG
 
     include ActiveRecord::Generators::Migration
@@ -31,9 +31,9 @@ module StepperMotor
     end
 
     def create_initializer
-      create_file "config/initializers/stepper_motor.rb", <<~RUBY
-        StepperMotor.scheduler = StepperMotor::ForwardScheduler.new
-      RUBY
+      # Take the initializer code from the test dummy app, it is the best place really.
+      initializer_code_from_dummy_app = File.read(__dir__ + "/../../test/dummy/config/initializers/stepper_motor.rb")
+      create_file "config/initializers/stepper_motor.rb", initializer_code_from_dummy_app
     end
 
     private

data/lib/generators/stepper_motor_migration_004.rb.erb

@@ -7,7 +7,7 @@ class StepperMotorMigration004 < ActiveRecord::Migration[<%= migration_version %
               name: :idx_journeys_one_per_hero_with_paused
 
     # Remove old indexes that only include 'ready' state
-    remove_index :stepper_motor_journeys, [:type, :hero_id, :hero_type], name: :one_per_hero_index, where: "allow_multiple = '0' AND state IN ('ready', 'performing')", algorithm: :concurrently 
+    remove_index :stepper_motor_journeys, [:type, :hero_id, :hero_type], name: :one_per_hero_index, where: "allow_multiple = '0' AND state IN ('ready', 'performing')" 
   end
 
   def down
@@ -19,6 +19,6 @@ class StepperMotorMigration004 < ActiveRecord::Migration[<%= migration_version %
               name: :one_per_hero_index
 
     # Remove new indexes
-    remove_index :stepper_motor_journeys, name: :idx_journeys_one_per_hero_with_paused, algorithm: :concurrently
+    remove_index :stepper_motor_journeys, name: :idx_journeys_one_per_hero_with_paused
   end
 end

data/lib/stepper_motor/base_job.rb

@@ -0,0 +1,5 @@
+# All StepperMotor job classes inherit from this one. It is available for
+# extension from StepperMotor.extend_base_job_class so that you can set
+# priority, include and prepend modules and so forth.
+class StepperMotor::BaseJob < ActiveJob::Base
+end

data/lib/stepper_motor/cyclic_scheduler.rb

@@ -21,7 +21,7 @@
 #
 # The scheduler needs to be configured in your cron table.
 class StepperMotor::CyclicScheduler < StepperMotor::ForwardScheduler
-  class RunSchedulingCycleJob < ActiveJob::Base
+  class RunSchedulingCycleJob < StepperMotor::BaseJob
     def perform
       scheduler = StepperMotor.scheduler
       return unless scheduler.is_a?(StepperMotor::CyclicScheduler)

data/lib/stepper_motor/delete_completed_journeys_job.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# The purpose of this job is to find journeys which have completed (finished or canceled) some
+# time ago and to delete them. The time is configured in the initializer.
+class StepperMotor::DeleteCompletedJourneysJob < StepperMotor::BaseJob
+  def perform(completed_for: StepperMotor.delete_completed_journeys_after, **)
+    return unless completed_for.present?
+
+    scope = StepperMotor::Journey.where(state: ["finished", "canceled"], updated_at: ..completed_for.ago)
+    scope.in_batches.each do |rel|
+      rel.delete_all
+    rescue => e
+      Rails.try(:error).try(:report, e)
+    end
+  end
+end

data/lib/stepper_motor/forward_scheduler.rb

@@ -19,7 +19,7 @@
 # scheduled to be performed). For good_job the {CyclicScheduler} is also likely to be a better option.
 class StepperMotor::ForwardScheduler
   def schedule(journey)
-    StepperMotor::PerformStepJobV2
+    StepperMotor::PerformStepJob
       .set(wait_until: journey.next_step_to_be_performed_at)
       .perform_later(journey_id: journey.id, journey_class_name: journey.class.to_s, idempotency_key: journey.idempotency_key)
   end

data/lib/stepper_motor/housekeeping_job.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class StepperMotor::HousekeepingJob < StepperMotor::BaseJob
+  def perform(**)
+    StepperMotor::RecoverStuckJourneysJob.perform_later
+    StepperMotor::DeleteCompletedJourneysJob.perform_later
+  end
+end

data/lib/stepper_motor/perform_step_job.rb

@@ -2,8 +2,18 @@
 
 require "active_job"
 
-class StepperMotor::PerformStepJob < ActiveJob::Base
-  def perform(journey_gid)
+class StepperMotor::PerformStepJob < StepperMotor::BaseJob
+  def perform(*posargs, **kwargs)
+    if posargs.length == 1 && kwargs.empty?
+      perform_via_journey_gid(*posargs)
+    else
+      perform_via_kwargs(**kwargs)
+    end
+  end
+
+  private
+
+  def perform_via_journey_gid(journey_gid)
     # Pass the GlobalID instead of the record itself, so that we can rescue the non-existing record
     # exception here as opposed to the job deserialization
     journey = begin
@@ -13,4 +23,17 @@ class StepperMotor::PerformStepJob < ActiveJob::Base
     end
     journey.perform_next_step!
   end
+
+  def perform_via_kwargs(journey_id:, journey_class_name:, idempotency_key: nil, **)
+    journey = begin
+      StepperMotor::Journey.find(journey_id)
+    rescue ActiveRecord::RecordNotFound
+      # The journey has been canceled and destroyed previously or elsewhere
+      return
+    end
+    journey.perform_next_step!(idempotency_key: idempotency_key)
+  end
 end
+
+# Alias for the previous job name
+StepperMotor::PerformStepJobV2 = StepperMotor::PerformStepJob

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

@@ -1,19 +1,20 @@
 # 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::RecoverStuckJourneysJobV1 < ActiveJob::Base
+class StepperMotor::RecoverStuckJourneysJob < StepperMotor::BaseJob
   DEFAULT_STUCK_FOR = 2.days
 
   def perform(stuck_for: DEFAULT_STUCK_FOR)
     StepperMotor::Journey.stuck(stuck_for.ago).find_each do |journey|
       journey.recover!
     rescue => e
-      Rails&.error&.report(e)
+      Rails.try(:error).try(:report, e)
     end
   end
 end
+
+# Alias for the previous job name
+StepperMotor::RecoverStuckJourneysJobV1 = StepperMotor::RecoverStuckJourneysJob

data/lib/stepper_motor/version.rb

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

data/lib/stepper_motor.rb

@@ -13,13 +13,25 @@ module StepperMotor
 
   autoload :Journey, File.dirname(__FILE__) + "/stepper_motor/journey.rb"
   autoload :Step, File.dirname(__FILE__) + "/stepper_motor/step.rb"
+
+  autoload :BaseJob, File.dirname(__FILE__) + "/stepper_motor/base_job.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 :PerformStepJobV2, File.dirname(__FILE__) + "/stepper_motor/perform_step_job.rb"
+  autoload :HousekeepingJob, File.dirname(__FILE__) + "/stepper_motor/housekeeping_job.rb"
+  autoload :DeleteCompletedJourneysJob, File.dirname(__FILE__) + "/stepper_motor/delete_completed_journeys_job.rb"
+  autoload :RecoverStuckJourneysJob, File.dirname(__FILE__) + "/stepper_motor/recover_stuck_journeys_job.rb"
+  autoload :RecoverStuckJourneysJobV1, File.dirname(__FILE__) + "/stepper_motor/recover_stuck_journeys_job.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"
   autoload :TestHelper, File.dirname(__FILE__) + "/stepper_motor/test_helper.rb"
 
   mattr_accessor :scheduler, default: ForwardScheduler.new
+  mattr_accessor :delete_completed_journeys_after, default: 30.days
+
+  # Extends the BaseJob of the library with any additional options
+  def self.extend_base_job(&blk)
+    BaseJob.class_eval(&blk)
+  end
 end

data/lib/tasks/stepper_motor_tasks.rake

@@ -3,6 +3,6 @@
 namespace :stepper_motor do
   desc "Recover all journeys hanging in the 'performing' state"
   task :recovery do
-    StepperMotor::RecoverStuckJourneysJobV1.perform_now
+    StepperMotor::RecoverStuckJourneysJob.perform_now
   end
 end

data/manual/MANUAL.md

@@ -1,14 +1,3 @@
-
-## Installation
-
-Add the gem to the application's Gemfile, and then generate and run the migration
-
-    $ bundle add stepper_motor
-    $ bundle install
-    $ bin/rails g stepper_motor:install --uuid # Pass "uuid" if you are using UUID for your primary and foreign keys
-    $ bin/rails db:migrate
-
-
 ## Intro
 
 `stepper_motor` solves a real, tangible problem in Rails apps - tracking activities over long periods of time. It does so in a durable, reentrant and consistent manner, utilizing the guarantees provided by your relational database you already have.

data/rbi/stepper_motor.rbi

@@ -2,7 +2,14 @@
 # StepperMotor is a module for building multi-step flows where steps are sequential and only
 # ever progress forward. The building block of StepperMotor is StepperMotor::Journey
 module StepperMotor
-  VERSION = T.let("0.1.9", T.untyped)
+  VERSION = T.let("0.1.11", T.untyped)
+  PerformStepJobV2 = T.let(StepperMotor::PerformStepJob, T.untyped)
+  RecoverStuckJourneysJobV1 = T.let(StepperMotor::RecoverStuckJourneysJob, T.untyped)
+
+  # sord omit - no YARD return type given, using untyped
+  # Extends the BaseJob of the library with any additional options
+  sig { params(blk: T.untyped).returns(T.untyped) }
+  def self.extend_base_job(&blk); end
 
   class Error < StandardError
   end
@@ -304,6 +311,12 @@ module StepperMotor
   class Railtie < Rails::Railtie
   end
 
+  # All StepperMotor job classes inherit from this one. It is available for
+  # extension from StepperMotor.extend_base_job_class so that you can set
+  # priority, include and prepend modules and so forth.
+  class BaseJob < ActiveJob::Base
+  end
+
   module 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
@@ -334,8 +347,8 @@ module StepperMotor
   class InstallGenerator < Rails::Generators::Base
     include ActiveRecord::Generators::Migration
     UUID_MESSAGE = T.let(<<~MSG, T.untyped)
-  If set, uuid type will be used for hero_id. Use this
-  if most of your models use UUD as primary key"
+  If set, uuid type will be used for hero_id of the Journeys, as well as for the Journey IDs.
+  Use this if most of your models use UUD as primary key"
 MSG
 
     # sord omit - no YARD return type given, using untyped
@@ -397,18 +410,37 @@ MSG
     sig { params(journey: T.untyped).returns(T.untyped) }
     def schedule(journey); end
 
-    class RunSchedulingCycleJob < ActiveJob::Base
+    class RunSchedulingCycleJob < StepperMotor::BaseJob
       # sord omit - no YARD return type given, using untyped
       sig { returns(T.untyped) }
       def perform; end
     end
   end
 
-  class PerformStepJob < ActiveJob::Base
+  class HousekeepingJob < StepperMotor::BaseJob
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def perform; end
+  end
+
+  class PerformStepJob < StepperMotor::BaseJob
+    # sord omit - no YARD type given for "*posargs", using untyped
+    # sord omit - no YARD type given for "**kwargs", using untyped
+    # sord omit - no YARD return type given, using untyped
+    sig { params(posargs: T.untyped, kwargs: T.untyped).returns(T.untyped) }
+    def perform(*posargs, **kwargs); end
+
     # sord omit - no YARD type given for "journey_gid", using untyped
     # sord omit - no YARD return type given, using untyped
     sig { params(journey_gid: T.untyped).returns(T.untyped) }
-    def perform(journey_gid); end
+    def perform_via_journey_gid(journey_gid); end
+
+    # sord omit - no YARD type given for "journey_id:", using untyped
+    # sord omit - no YARD type given for "journey_class_name:", using untyped
+    # sord omit - no YARD type given for "idempotency_key:", using untyped
+    # sord omit - no YARD return type given, using untyped
+    sig { params(journey_id: T.untyped, journey_class_name: T.untyped, idempotency_key: T.untyped).returns(T.untyped) }
+    def perform_via_kwargs(journey_id:, journey_class_name:, idempotency_key: nil); end
   end
 
   # The forward scheduler enqueues a job for every Journey that
@@ -435,20 +467,11 @@ MSG
     def schedule(journey); end
   end
 
-  class PerformStepJobV2 < ActiveJob::Base
-    # sord omit - no YARD type given for "journey_id:", using untyped
-    # sord omit - no YARD type given for "journey_class_name:", using untyped
-    # sord omit - no YARD type given for "idempotency_key:", using untyped
-    # sord omit - no YARD return type given, using untyped
-    sig { params(journey_id: T.untyped, journey_class_name: T.untyped, idempotency_key: T.untyped).returns(T.untyped) }
-    def perform(journey_id:, journey_class_name:, idempotency_key: nil); end
-  end
-
   # 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 RecoverStuckJourneysJobV1 < ActiveJob::Base
+  class RecoverStuckJourneysJob < StepperMotor::BaseJob
     DEFAULT_STUCK_FOR = T.let(2.days, T.untyped)
 
     # sord omit - no YARD type given for "stuck_for:", using untyped
@@ -456,4 +479,13 @@ MSG
     sig { params(stuck_for: T.untyped).returns(T.untyped) }
     def perform(stuck_for: DEFAULT_STUCK_FOR); end
   end
+
+  # The purpose of this job is to find journeys which have completed (finished or canceled) some
+  # time ago and to delete them. The time is configured in the initializer.
+  class DeleteCompletedJourneysJob < StepperMotor::BaseJob
+    # sord omit - no YARD type given for "completed_for:", using untyped
+    # sord omit - no YARD return type given, using untyped
+    sig { params(completed_for: T.untyped).returns(T.untyped) }
+    def perform(completed_for: StepperMotor.delete_completed_journeys_after); end
+  end
 end

data/sig/stepper_motor.rbs

@@ -2,6 +2,12 @@
 # ever progress forward. The building block of StepperMotor is StepperMotor::Journey
 module StepperMotor
   VERSION: untyped
+  PerformStepJobV2: untyped
+  RecoverStuckJourneysJobV1: untyped
+
+  # sord omit - no YARD return type given, using untyped
+  # Extends the BaseJob of the library with any additional options
+  def self.extend_base_job: () -> untyped
 
   class Error < StandardError
   end
@@ -269,6 +275,12 @@ module StepperMotor
   class Railtie < Rails::Railtie
   end
 
+  # All StepperMotor job classes inherit from this one. It is available for
+  # extension from StepperMotor.extend_base_job_class so that you can set
+  # priority, include and prepend modules and so forth.
+  class BaseJob < ActiveJob::Base
+  end
+
   module 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
@@ -350,16 +362,32 @@ module StepperMotor
     # sord omit - no YARD return type given, using untyped
     def schedule: (untyped journey) -> untyped
 
-    class RunSchedulingCycleJob < ActiveJob::Base
+    class RunSchedulingCycleJob < StepperMotor::BaseJob
       # sord omit - no YARD return type given, using untyped
       def perform: () -> untyped
     end
   end
 
-  class PerformStepJob < ActiveJob::Base
+  class HousekeepingJob < StepperMotor::BaseJob
+    # sord omit - no YARD return type given, using untyped
+    def perform: () -> untyped
+  end
+
+  class PerformStepJob < StepperMotor::BaseJob
+    # sord omit - no YARD type given for "*posargs", using untyped
+    # sord omit - no YARD type given for "**kwargs", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def perform: (*untyped posargs, **untyped kwargs) -> untyped
+
     # sord omit - no YARD type given for "journey_gid", using untyped
     # sord omit - no YARD return type given, using untyped
-    def perform: (untyped journey_gid) -> untyped
+    def perform_via_journey_gid: (untyped journey_gid) -> untyped
+
+    # sord omit - no YARD type given for "journey_id:", using untyped
+    # sord omit - no YARD type given for "journey_class_name:", using untyped
+    # sord omit - no YARD type given for "idempotency_key:", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def perform_via_kwargs: (journey_id: untyped, journey_class_name: untyped, ?idempotency_key: untyped) -> untyped
   end
 
   # The forward scheduler enqueues a job for every Journey that
@@ -385,23 +413,23 @@ module StepperMotor
     def schedule: (untyped journey) -> untyped
   end
 
-  class PerformStepJobV2 < ActiveJob::Base
-    # sord omit - no YARD type given for "journey_id:", using untyped
-    # sord omit - no YARD type given for "journey_class_name:", using untyped
-    # sord omit - no YARD type given for "idempotency_key:", using untyped
-    # sord omit - no YARD return type given, using untyped
-    def perform: (journey_id: untyped, journey_class_name: untyped, ?idempotency_key: untyped) -> untyped
-  end
-
   # 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 RecoverStuckJourneysJobV1 < ActiveJob::Base
+  class RecoverStuckJourneysJob < StepperMotor::BaseJob
     DEFAULT_STUCK_FOR: untyped
 
     # sord omit - no YARD type given for "stuck_for:", using untyped
     # sord omit - no YARD return type given, using untyped
     def perform: (?stuck_for: untyped) -> untyped
   end
+
+  # The purpose of this job is to find journeys which have completed (finished or canceled) some
+  # time ago and to delete them. The time is configured in the initializer.
+  class DeleteCompletedJourneysJob < StepperMotor::BaseJob
+    # sord omit - no YARD type given for "completed_for:", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def perform: (?completed_for: untyped) -> untyped
+  end
 end

data/stepper_motor.gemspec

@@ -38,7 +38,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rails", "~> 7.0"
   spec.add_development_dependency "sqlite3"
   spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "standard"
+  spec.add_development_dependency "standard", "~> 1.50.0", "< 2.0"
   spec.add_development_dependency "magic_frozen_string_literal"
   spec.add_development_dependency "yard"
   spec.add_development_dependency "redcarpet" # needed for the yard gem to enable Github Flavored Markdown

data/test/dummy/config/initializers/stepper_motor.rb

@@ -1 +1,40 @@
+# frozen_string_literal: true
+
+# Sets the scheduler. The ForwardScheduler will enqueue jobs for performing steps
+# regardless of how far in the future a step needs to be taken. The CyclicScheduler
+# will only enqueue jobs for steps which are to be performed soon. If you want to use
+# the CyclicScheduler, you will need to configure it for the proper interval duration:
+#
+#   StepperMotor.scheduler = StepperMotor::CyclicScheduler.new(cycle_duration: 30.minutes)
+#
+# and add its cycle job into your recurring jobs table. For example, for solid_queue:
+#
+#   stepper_motor_houseleeping:
+#     schedule: "*/30 * * * *" # Every 30 minutes
+#     class: "StepperMotor::CyclicScheduler::RunSchedulingCycleJob"
+#
+# The cadence of the cyclic scheduler and the cadence of your cron job should be equal.
+#
+# If your queue is not susceptible to performance degradation with large numbers of
+# "far future" jobs and allows scheduling "far ahead" - you can use the `ForwardScheduler`
+# which is the default.
 StepperMotor.scheduler = StepperMotor::ForwardScheduler.new
+
+# Sets the amount of time after which completed (finished and canceled)
+# Journeys are going to be deleted from the database. If you want to keep
+# them in the database indefinitely, set this parameter to `nil`.
+# To perform the actual cleanups, add the `StepperMotor::HousekeepingJob` to your
+# recurring jobs table. For example, for solid_queue:
+#
+#   stepper_motor_housekeeping:
+#     schedule: "*/30 * * * *" # Every 30 minutes
+#     class: "StepperMotor::HousekeepingJob"
+StepperMotor.delete_completed_journeys_after = 30.days
+
+# Extends the base StepperMotor ActiveJob with any calls you would use to customise a
+# job in your codebase. At the minimum, we recommend setting all StepperMotor job priorities
+# to "high" - according to the priority denomination you are using.
+# StepperMotor.extend_base_job do
+#   priority :high
+#   discard_on ActiveRecord::NotFound
+# end

data/test/dummy/db/migrate/{20250525132526_stepper_motor_migration_004.rb → 20250528141038_stepper_motor_migration_004.rb}

@@ -7,7 +7,7 @@ class StepperMotorMigration004 < ActiveRecord::Migration[7.2]
               name: :idx_journeys_one_per_hero_with_paused
 
     # Remove old indexes that only include 'ready' state
-    remove_index :stepper_motor_journeys, [:type, :hero_id, :hero_type], name: :one_per_hero_index, where: "allow_multiple = '0' AND state IN ('ready', 'performing')", algorithm: :concurrently 
+    remove_index :stepper_motor_journeys, [:type, :hero_id, :hero_type], name: :one_per_hero_index, where: "allow_multiple = '0' AND state IN ('ready', 'performing')" 
   end
 
   def down
@@ -19,6 +19,6 @@ class StepperMotorMigration004 < ActiveRecord::Migration[7.2]
               name: :one_per_hero_index
 
     # Remove new indexes
-    remove_index :stepper_motor_journeys, name: :idx_journeys_one_per_hero_with_paused, algorithm: :concurrently
+    remove_index :stepper_motor_journeys, name: :idx_journeys_one_per_hero_with_paused
   end
 end

data/test/dummy/db/schema.rb

@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[7.2].define(version: 2025_05_25_132526) do
+ActiveRecord::Schema[7.2].define(version: 2025_05_28_141038) do
   create_table "stepper_motor_journeys", force: :cascade do |t|
     t.string "type", null: false
     t.string "state", default: "ready"

data/test/stepper_motor/completed_journeys_cleanup_test.rb

@@ -0,0 +1,96 @@
+require "test_helper"
+
+class CompletedJourneysCleanupTest < ActiveSupport::TestCase
+  include SideEffects::TestHelper
+
+  test "defines a variable on StepperMotor and sets it to a default value" do
+    assert StepperMotor.delete_completed_journeys_after
+    assert_equal 30.days, StepperMotor.delete_completed_journeys_after
+  end
+
+  test "cleans up finished journeys" do
+    previous_setting = StepperMotor.delete_completed_journeys_after
+
+    journey_class = create_journey_subclass do
+      step wait: 20.minutes do
+        SideEffects.touch! :a_step
+      end
+    end
+    journey = journey_class.create!
+    another_journey = journey_class.create!
+
+    assert_no_changes "StepperMotor::Journey.count" do
+      StepperMotor::DeleteCompletedJourneysJob.new.perform
+    end
+
+    travel_to Time.current + 20.minutes + 1.second
+    journey.perform_next_step!
+
+    assert SideEffects.produced?(:a_step)
+    assert journey.finished?
+
+    assert_no_changes "StepperMotor::Journey.count" do
+      StepperMotor::DeleteCompletedJourneysJob.new.perform
+    end
+
+    StepperMotor.delete_completed_journeys_after = 7.minutes
+    travel_to Time.current + 7.minutes + 1.second
+
+    assert_changes "StepperMotor::Journey.count", -1 do
+      StepperMotor::DeleteCompletedJourneysJob.new.perform
+    end
+
+    assert_raises(ActiveRecord::RecordNotFound) { journey.reload }
+    assert_nothing_raised { another_journey.reload }
+  ensure
+    StepperMotor.delete_completed_journeys_after = previous_setting
+  end
+
+  test "cleans up canceled journeys" do
+    previous_setting = StepperMotor.delete_completed_journeys_after
+
+    journey_class = create_journey_subclass do
+      step wait: 20.minutes do
+        # noop
+      end
+    end
+    journey = journey_class.create!
+    journey.cancel!
+
+    assert_no_changes "StepperMotor::Journey.count" do
+      StepperMotor::DeleteCompletedJourneysJob.new.perform
+    end
+
+    StepperMotor.delete_completed_journeys_after = 7.minutes
+    travel_to Time.current + 7.minutes + 1.second
+
+    assert_changes "StepperMotor::Journey.count", -1 do
+      StepperMotor::DeleteCompletedJourneysJob.new.perform
+    end
+
+    assert_raises(ActiveRecord::RecordNotFound) { journey.reload }
+  ensure
+    StepperMotor.delete_completed_journeys_after = previous_setting
+  end
+
+  test "does not delete any journeys if the setting is set to nil" do
+    previous_setting = StepperMotor.delete_completed_journeys_after
+    StepperMotor.delete_completed_journeys_after = nil
+
+    journey_class = create_journey_subclass do
+      step wait: 20.minutes do
+        # noop
+      end
+    end
+    journey = journey_class.create!
+    journey.cancel!
+
+    travel_to Time.current + 365.days
+    assert_no_changes "StepperMotor::Journey.count" do
+      StepperMotor::DeleteCompletedJourneysJob.new.perform
+    end
+    assert_nothing_raised { journey.reload }
+  ensure
+    StepperMotor.delete_completed_journeys_after = previous_setting
+  end
+end

data/test/stepper_motor/configuration_test.rb

@@ -0,0 +1,8 @@
+require "test_helper"
+
+class ConfigurationTest < ActiveSupport::TestCase
+  test "allows extending the base job" do
+    retrieved_name = StepperMotor.extend_base_job { name }
+    assert_equal "StepperMotor::BaseJob", retrieved_name
+  end
+end

data/test/stepper_motor/cyclic_scheduler_test.rb

@@ -39,7 +39,7 @@ class CyclicSchedulerTest < ActiveSupport::TestCase
     scheduler = StepperMotor::CyclicScheduler.new(cycle_duration: 40.minutes)
     StepperMotor.scheduler = scheduler
 
-    assert_enqueued_jobs 1, only: StepperMotor::PerformStepJobV2 do
+    assert_enqueued_jobs 1, only: StepperMotor::PerformStepJob do
       far_future_journey_class.create!
     end
   end
@@ -54,7 +54,7 @@ class CyclicSchedulerTest < ActiveSupport::TestCase
     end
     journey.update!(next_step_to_be_performed_at: 10.minutes.ago)
 
-    assert_enqueued_jobs 1, only: StepperMotor::PerformStepJobV2 do
+    assert_enqueued_jobs 1, only: StepperMotor::PerformStepJob do
       scheduler.run_scheduling_cycle
     end
   end

data/test/stepper_motor/forward_scheduler_test.rb

@@ -31,7 +31,7 @@ class ForwardSchedulerTest < ActiveSupport::TestCase
     assert_equal 1, enqueued_jobs.size
     job = enqueued_jobs.first
 
-    assert_equal "StepperMotor::PerformStepJobV2", job["job_class"]
+    assert_equal "StepperMotor::PerformStepJob", job["job_class"]
     assert_not_nil job["scheduled_at"]
 
     scheduled_at = Time.parse(job["scheduled_at"])

data/test/stepper_motor/housekeeping_job_test.rb

@@ -0,0 +1,13 @@
+require "test_helper"
+
+class HousekeepingJobTest < ActiveSupport::TestCase
+  include ActiveJob::TestHelper
+
+  test "runs without exceptions and enqueues the two actual jobs" do
+    assert_nothing_raised do
+      StepperMotor::HousekeepingJob.perform_now
+    end
+
+    assert_enqueued_jobs 2
+  end
+end

data/test/stepper_motor/perform_step_job_test.rb

@@ -0,0 +1,60 @@
+require "test_helper"
+
+class PerformStepJobTest < ActiveSupport::TestCase
+  include SideEffects::TestHelper
+
+  test "exposes the V2 variant in a constant to allow old jobs to be unserialized" do
+    assert defined?(StepperMotor::PerformStepJobV2)
+    assert_equal StepperMotor::PerformStepJob, StepperMotor::PerformStepJobV2
+  end
+
+  test "allows perform() with a GlobalID as argument" do
+    journey = create_journey_subclass do
+      step do
+        # noop
+      end
+    end.create!
+
+    assert_nothing_raised { StepperMotor::PerformStepJob.new.perform(journey.to_global_id) }
+    assert journey.reload.finished?
+  end
+
+  test "allows perform() with the journey class name and ID" do
+    journey = create_journey_subclass do
+      step do
+        # noop
+      end
+    end.create!
+
+    assert_nothing_raised do
+      StepperMotor::PerformStepJob.new.perform(journey_id: journey.id, journey_class_name: journey.class.name)
+    end
+    assert journey.reload.finished?
+  end
+
+  test "allows perform() with the journey class name, ID and idempotency key" do
+    journey = create_journey_subclass do
+      step do
+        # noop
+      end
+    end.create!
+
+    assert_nothing_raised do
+      StepperMotor::PerformStepJob.new.perform(journey_id: journey.id, journey_class_name: journey.class.name, idempotency_key: journey.idempotency_key)
+    end
+    assert journey.reload.finished?
+  end
+
+  test "skips without exceptions if the idempotency key is incorrect" do
+    journey = create_journey_subclass do
+      step do
+        # noop
+      end
+    end.create!
+
+    assert_nothing_raised do
+      StepperMotor::PerformStepJob.new.perform(journey_id: journey.id, journey_class_name: journey.class.name, idempotency_key: "wrong")
+    end
+    assert journey.reload.ready?
+  end
+end

data/test/stepper_motor/recover_stuck_journeys_job_test.rb

@@ -7,6 +7,11 @@ class RecoverStuckJourneysJobTest < ActiveSupport::TestCase
     StepperMotor::Journey.delete_all
   end
 
+  test "still has the previous job class name available to allow older jobs to be unserialized" do
+    assert defined?(StepperMotor::RecoverStuckJourneysJobV1)
+    assert_equal StepperMotor::RecoverStuckJourneysJob, StepperMotor::RecoverStuckJourneysJobV1
+  end
+
   test "handles recovery from a background job" do
     stuck_journey_class1 = create_journey_subclass do
       self.when_stuck = :cancel
@@ -52,12 +57,12 @@ class RecoverStuckJourneysJobTest < ActiveSupport::TestCase
     assert journey_to_cancel.reload.performing?
     assert journey_to_reattempt.reload.performing?
 
-    StepperMotor::RecoverStuckJourneysJobV1.perform_now(stuck_for: 2.days)
+    StepperMotor::RecoverStuckJourneysJob.perform_now(stuck_for: 2.days)
     assert journey_to_cancel.reload.performing?
     assert journey_to_reattempt.reload.performing?
 
     travel_to Time.now + 2.days + 1.second
-    StepperMotor::RecoverStuckJourneysJobV1.perform_now(stuck_for: 2.days)
+    StepperMotor::RecoverStuckJourneysJob.perform_now(stuck_for: 2.days)
 
     assert journey_to_cancel.reload.canceled?
     assert journey_to_reattempt.reload.ready?
@@ -83,7 +88,7 @@ class RecoverStuckJourneysJobTest < ActiveSupport::TestCase
     journey_to_cancel.class.update_all(type: "UnknownJourneySubclass")
 
     assert_nothing_raised do
-      StepperMotor::RecoverStuckJourneysJobV1.perform_now(stuck_for: 2.days)
+      StepperMotor::RecoverStuckJourneysJob.perform_now(stuck_for: 2.days)
     end
   end
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stepper_motor
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.1.11
 platform: ruby
 authors:
 - Julik Tarkhanov
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-25 00:00:00.000000000 Z
+date: 2025-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -111,16 +112,22 @@ dependencies:
   name: standard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.50.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.50.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: magic_frozen_string_literal
   requirement: !ruby/object:Gem::Requirement
@@ -200,15 +207,17 @@ files:
 - lib/generators/stepper_motor_migration_003.rb.erb
 - lib/generators/stepper_motor_migration_004.rb.erb
 - lib/stepper_motor.rb
+- lib/stepper_motor/base_job.rb
 - lib/stepper_motor/cyclic_scheduler.rb
+- lib/stepper_motor/delete_completed_journeys_job.rb
 - lib/stepper_motor/forward_scheduler.rb
+- lib/stepper_motor/housekeeping_job.rb
 - lib/stepper_motor/journey.rb
 - lib/stepper_motor/journey/flow_control.rb
 - lib/stepper_motor/journey/recovery.rb
 - lib/stepper_motor/perform_step_job.rb
-- lib/stepper_motor/perform_step_job_v2.rb
 - lib/stepper_motor/railtie.rb
-- lib/stepper_motor/recover_stuck_journeys_job_v1.rb
+- lib/stepper_motor/recover_stuck_journeys_job.rb
 - lib/stepper_motor/step.rb
 - lib/stepper_motor/test_helper.rb
 - lib/stepper_motor/version.rb
@@ -253,7 +262,7 @@ files:
 - test/dummy/db/migrate/20250525132523_stepper_motor_migration_001.rb
 - test/dummy/db/migrate/20250525132524_stepper_motor_migration_002.rb
 - test/dummy/db/migrate/20250525132525_stepper_motor_migration_003.rb
-- test/dummy/db/migrate/20250525132526_stepper_motor_migration_004.rb
+- test/dummy/db/migrate/20250528141038_stepper_motor_migration_004.rb
 - test/dummy/db/schema.rb
 - test/dummy/public/400.html
 - test/dummy/public/404.html
@@ -263,14 +272,18 @@ files:
 - test/dummy/public/icon.png
 - test/dummy/public/icon.svg
 - test/side_effects_helper.rb
+- test/stepper_motor/completed_journeys_cleanup_test.rb
+- test/stepper_motor/configuration_test.rb
 - test/stepper_motor/cyclic_scheduler_test.rb
 - test/stepper_motor/forward_scheduler_test.rb
+- test/stepper_motor/housekeeping_job_test.rb
 - test/stepper_motor/journey/exception_handling_test.rb
 - test/stepper_motor/journey/flow_control_test.rb
 - test/stepper_motor/journey/idempotency_test.rb
 - test/stepper_motor/journey/step_definition_test.rb
 - test/stepper_motor/journey/uniqueness_test.rb
 - test/stepper_motor/journey_test.rb
+- test/stepper_motor/perform_step_job_test.rb
 - test/stepper_motor/recover_stuck_journeys_job_test.rb
 - test/stepper_motor/recovery_test.rb
 - test/stepper_motor/test_helper_test.rb
@@ -284,6 +297,7 @@ metadata:
   homepage_uri: https://steppermotor.dev
   source_code_uri: https://github.com/stepper-motor/stepper_motor
   changelog_uri: https://github.com/stepper-motor/stepper_motor/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -298,7 +312,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.6
+rubygems_version: 3.4.10
+signing_key:
 specification_version: 4
 summary: Effortless step workflows that embed nicely inside Rails
 test_files: []

data/lib/stepper_motor/perform_step_job_v2.rb

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