stepper_motor 0.1.12 → 0.1.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dcbfb106c1b6c9c74cef277a3bedec00c970d5264856ae92671b6f2302936eaa
-  data.tar.gz: a351a974b2ed5af98f20c8e816e43aac19982539054c7db1e3b1290d2d6a2538
+  metadata.gz: 4b94d7f405351309bd1fbda83b352031795cbee87aad100d412d847e3d03543c
+  data.tar.gz: 59ecde85caacac0c7e65f6a0c527676bac4700b84fa39ce55443e81592023738
 SHA512:
-  metadata.gz: 6a7f3190a99a62537b17ccfdfd76f1c4879a5b5c054395ffbd1d4ccaf7da469f96e2198954adbb2db79571b046b772ea37daf3865f27c23ea7d3a2b75f505699
-  data.tar.gz: 8f999b8fb9e599d6cfac817a82cc4640902d9812a296f9643cd80d0632099f94140645f9ad55dcbd1a043e1c6f25df3084a0cc23ab88b24ac206dab2b991c302
+  metadata.gz: 5305f1f98eb8b8c630e45309280fae524ec458d15a75362e647a36e22fd29ca0fe1a7ecbbba186ed60f33b64b7b6b875e66878280e21a6a3196473652b82f098
+  data.tar.gz: 2e6db70cf8ad6b844c4d7a38eab6f087f785b1a112f446844e25d6d943bffd3f3b71da6bd7baa69c7249a7978a5538d2572235b3f90475b01af8be0d07074cfd

data/.github/workflows/ci.yml

@@ -7,6 +7,7 @@ on:
 
 jobs:
   lint:
+    name: "Lint (standardrb)"
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
@@ -22,17 +23,45 @@ jobs:
         run: bundle exec standardrb
 
   test:
+    name: "Tests (${{ matrix.database.name }})"
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        database:
+          - { name: 'PostgreSQL', url: 'postgresql://postgres:postgres@localhost:5432/stepper_motor_test' }
+          - { name: 'MySQL', url: 'mysql2://root:root@127.0.0.1:3306/stepper_motor_test?host=127.0.0.1' }
+          - { name: 'SQLite', url: 'sqlite3:db/test.sqlite3' }
+
+    services:
+      postgres:
+        image: postgres:14
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: stepper_motor_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      mysql:
+        image: mysql:8.0
+        env:
+          MYSQL_ROOT_PASSWORD: root
+          MYSQL_DATABASE: stepper_motor_test
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd "mysqladmin ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
 
-    # services:
-    #  redis:
-    #    image: redis
-    #    ports:
-    #      - 6379:6379
-    #    options: --health-cmd "redis-cli ping" --health-interval 10s --health-timeout 5s --health-retries 5
     steps:
       - name: Install packages
-        run: sudo apt-get update && sudo apt-get install --no-install-recommends -y build-essential git libyaml-dev pkg-config google-chrome-stable
+        run: sudo apt-get update && sudo apt-get install --no-install-recommends -y build-essential git libyaml-dev pkg-config
 
       - name: Checkout code
         uses: actions/checkout@v4
@@ -43,9 +72,22 @@ jobs:
           ruby-version: 3.2.2
           bundler-cache: true
 
+      - name: Remove existing schema.rb
+        run: rm -f test/dummy/db/schema.rb
+
+      - name: Setup database
+        env:
+          RAILS_ENV: test
+          DATABASE_URL: ${{ matrix.database.url }}
+        run: |
+          cd test/dummy
+          bundle exec rails db:create
+          bundle exec rails db:migrate
+          cd ../..
+
       - name: Run tests
         env:
           RAILS_ENV: test
-          # REDIS_URL: redis://localhost:6379/0
+          DATABASE_URL: ${{ matrix.database.url }}
         run: bin/test
 

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.1.16] - 2025-06-20
+
+- Add `skip!` flow control method to skip the current (or next) step and move on to the subsequent step, or finish the journey.
+- Rename `if:` parameter to `skip_if:` for better clarity. The `if:` parameter is still supported for brevity.
+
+## [0.1.15] - 2025-06-20
+
+- Add `if:` condition allowing steps to be skipped. The `if:` can be a boolean, a callable or a symbol for a method name. The method should be on the Journey.
+  
+## [0.1.14] - 2025-06-10
+
+- Since MySQL does not support partial indexes, use a generated column for the uniqueness checks. Other indexes
+  which are set up as partial indexes just become full indexes - that will make them larger on MySQL but the functionality
+  is going to be the same. This is a tradeoff but it seems sensible for the time being.
+
 ## [0.1.12] - 2025-06-08
 
 - Ensure base job extension gets done via the reloader, so that app classes are available

data/lib/generators/stepper_motor_migration_005.rb.erb

@@ -0,0 +1,58 @@
+class StepperMotorMigration005 < ActiveRecord::Migration[<%= migration_version %>]
+  def up
+    unless mysql?
+      say "Skipping migration as it is only used with MySQL (mysql2 or trilogy)"
+      return
+    end
+
+    # Add generated column that combines the state, type, hero_id, and hero_type
+    # The column will be NULL if any of the components is NULL
+    execute <<-SQL
+      ALTER TABLE stepper_motor_journeys
+      ADD COLUMN journey_uniq_col_generated VARCHAR(255) GENERATED ALWAYS AS (
+        CASE 
+          WHEN state IN ('ready', 'performing', 'paused') 
+          AND allow_multiple = 0 
+          AND type IS NOT NULL 
+          AND hero_id IS NOT NULL 
+          AND hero_type IS NOT NULL
+          THEN CONCAT(type, ':', hero_id, ':', hero_type)
+          ELSE NULL
+        END
+      ) STORED
+    SQL
+
+    # Add unique index on the generated column with MySQL-specific name
+    add_index :stepper_motor_journeys, :journey_uniq_col_generated, 
+              unique: true, 
+              name: :idx_journeys_one_per_hero_mysql_generated
+
+    # Remove old indexes that include 'ready', 'performing', and 'paused' states
+    remove_index :stepper_motor_journeys, name: :idx_journeys_one_per_hero_with_paused
+  end
+
+  def down
+    unless mysql?
+      say "Skipping migration as it is only used with MySQL (mysql2 or trilogy)"
+      return
+    end
+
+    # Remove the generated column and its index
+    remove_index :stepper_motor_journeys, name: :idx_journeys_one_per_hero_mysql_generated
+    remove_column :stepper_motor_journeys, :journey_uniq_col_generated
+
+    # Recreate old indexes
+    quoted_false = connection.quote(false)
+    add_index :stepper_motor_journeys, [:type, :hero_id, :hero_type], 
+              where: "allow_multiple = '#{quoted_false}' AND state IN ('ready', 'performing', 'paused')", 
+              unique: true, 
+              name: :idx_journeys_one_per_hero_with_paused
+  end
+
+  private
+
+  def mysql?
+    adapter = connection.adapter_name.downcase
+    adapter == 'mysql2' || adapter == 'trilogy'
+  end
+end 

data/lib/stepper_motor/journey/flow_control.rb

@@ -27,6 +27,55 @@ module StepperMotor::Journey::FlowControl
     throw :abort_step if @current_step_definition
   end
 
+  # Is used to skip the current step and proceed to the next step in the journey. This is useful when you want to
+  # conditionally skip a step based on some business logic without canceling the entire journey. For example,
+  # you might want to skip a reminder email step if the user has already taken the required action.
+  #
+  # If there are more steps after the current step, `skip!` will schedule the next step to be performed.
+  # If the current step is the last step in the journey, `skip!` will finish the journey.
+  #
+  # `skip!` may be called within a step or outside of a step for journeys in the `ready` state.
+  # When called outside of a step, it will skip the next scheduled step and proceed to the following step.
+  #
+  # @return void
+  def skip!
+    if @current_step_definition
+      # Called within a step - set flag to skip current step
+      @skip_current_step = true
+      throw :abort_step if @current_step_definition
+    else
+      # Called outside of a step - skip next scheduled step
+      with_lock do
+        raise "skip! can only be used on journeys in the `ready` state, but was in #{state.inspect}" unless ready?
+
+        current_step_name = next_step_name
+        current_step_definition = lookup_step_definition(current_step_name)
+
+        unless current_step_definition
+          logger.warn { "no step definition found for #{current_step_name} - finishing journey" }
+          finished!
+          update!(previous_step_name: current_step_name, next_step_name: nil)
+          return
+        end
+
+        current_step_seq = current_step_definition.seq
+        next_step_definition = step_definitions[current_step_seq + 1]
+
+        if next_step_definition
+          # There are more steps after this one - schedule the next step
+          logger.info { "skipping scheduled step #{current_step_name}, will continue to #{next_step_definition.name}" }
+          set_next_step_and_enqueue(next_step_definition)
+          ready!
+        else
+          # This is the last step - finish the journey
+          logger.info { "skipping scheduled step #{current_step_name}, finishing journey" }
+          finished!
+          update!(previous_step_name: current_step_name, next_step_name: nil)
+        end
+      end
+    end
+  end
+
   # Is used to pause a Journey at any point. The "paused" state is similar to the "ready" state, except that "perform_next_step!" on the
   # journey will do nothing - even if it is scheduled to be performed. Pausing a Journey can be useful in the following situations:
   #

data/lib/stepper_motor/journey.rb

@@ -72,15 +72,41 @@ module StepperMotor
     #    When the journey gets scheduled, the triggering job is going to be delayed by this amount of time, and the
     #    `next_step_to_be_performed_at` attribute will be set to the current time plus the wait duration. Mutually exclusive with `after:`
     # @param after[Float,#to_f,ActiveSupport::Duration] the amount of time this step should wait before getting performed
-    #    including all the previous waits. This allows you to set the wait time based on the time after the journey started, as opposed
-    #    to when the previous step has completed. When the journey gets scheduled, the triggering job is going to be delayed by this
-    #    amount of time _minus the `wait` values of the preceding steps, and the
-    #    `next_step_to_be_performed_at` attribute will be set to the current time. The `after` value gets converted into the `wait`
-    #    value and passed to the step definition. Mutually exclusive with `wait:`
+    #    including all the previous waits. This allows you to set the wait time based on the time after the journey started,
+    #    as opposed to when the previous step has completed. When the journey gets scheduled, the triggering job is going to
+    #    be delayed by this amount of time _minus the `wait` values of the preceding steps, and the `next_step_to_be_performed_at`
+    #    attribute will be set to the current time. The `after` value gets converted into the `wait` value and passed to the step definition.
+    #    Mutually exclusive with `wait:`
     # @param on_exception[Symbol] See {StepperMotor::Step#on_exception}
-    # @param additional_step_definition_options Any remaining options get passed to `StepperMotor::Step.new` as keyword arguments.
+    # @param skip_if[TrueClass,FalseClass,Symbol,Proc] condition to check before performing the step. If a symbol is provided,
+    #    it will call the method on the Journey. If a block is provided, it will be executed with the Journey as context.
+    #    The step will be skipped if the condition returns a truthy value.
+    # @param if[TrueClass,FalseClass,Symbol,Proc] condition to check before performing the step. If a symbol is provided,
+    #    it will call the method on the Journey. If a block is provided, it will be executed with the Journey as context.
+    #    The step will be performed if the condition returns a truthy value. and skipped otherwise. Inverse of `skip_if`.
+    # @param additional_step_definition_options[Hash] Any remaining options get passed to `StepperMotor::Step.new` as keyword arguments.
     # @return [StepperMotor::Step] the step definition that has been created
-    def self.step(name = nil, wait: nil, after: nil, on_exception: :pause!, **additional_step_definition_options, &blk)
+    def self.step(name = nil, wait: nil, after: nil, **additional_step_definition_options, &blk)
+      # Handle the if: alias for backward compatibility
+      if additional_step_definition_options.key?(:if) && additional_step_definition_options.key?(:skip_if)
+        raise StepConfigurationError, "Either skip_if: or if: can be specified, but not both"
+      end
+      if additional_step_definition_options.key?(:if)
+        if_condition = additional_step_definition_options.delete(:if)
+        # Convert if: to skip_if: by negating either the actual value or the return value of the callable
+        # if: truthy means perform, skip_if: truthy means "skip"
+        additional_step_definition_options[:skip_if] = case if_condition
+        when true, false, nil
+          !if_condition
+        when Symbol
+          # For symbols, we need to create a proc that negates the result
+          -> { !send(if_condition) }
+        else
+          # For callables, we need to create a proc that negates the result
+          -> { !instance_exec(&if_condition) }
+        end
+      end
+
       wait = if wait && after
         raise StepConfigurationError, "Either wait: or after: can be specified, but not both"
       elsif !wait && !after
@@ -97,8 +123,8 @@ module StepperMotor
         raise StepConfigurationError, <<~MSG
           Step #{step_definitions.length + 1} of #{self} has no explicit name,
           and no block with step definition has been provided. Without a name the step
-          must be defined with a block to execute. If you want an instance method to be
-          executed as a step, pass the name of the method as the name of the step.
+          must be defined with a block to execute. If you want an instance method of
+          this Journey to be used as the step, pass the name of the method as the name of the step.
         MSG
       end
 
@@ -109,7 +135,7 @@ module StepperMotor
       raise StepConfigurationError, "Step named #{name.inspect} already defined" if known_step_names.include?(name)
 
       # Create the step definition
-      StepperMotor::Step.new(name: name, wait: wait, seq: step_definitions.length, on_exception:, **additional_step_definition_options, &blk).tap do |step_definition|
+      StepperMotor::Step.new(name: name, wait: wait, seq: step_definitions.length, **additional_step_definition_options, &blk).tap do |step_definition|
         # As per Rails docs: you need to be aware when using class_attribute with mutable structures
         # as Array or Hash. In such cases, you don't want to do changes in place. Instead use setters.
         # See https://apidock.com/rails/v7.1.3.2/Class/class_attribute
@@ -229,6 +255,22 @@ module StepperMotor
         logger.info { "will reattempt #{current_step_name} in #{@reattempt_after} seconds" }
         set_next_step_and_enqueue(@current_step_definition, wait: @reattempt_after)
         ready!
+      elsif @skip_current_step
+        # The step asked to be skipped
+        current_step_seq = @current_step_definition.seq
+        next_step_definition = step_definitions[current_step_seq + 1]
+
+        if next_step_definition
+          # There are more steps after this one - schedule the next step
+          logger.info { "skipping current step #{current_step_name}, will continue to #{next_step_definition.name}" }
+          set_next_step_and_enqueue(next_step_definition)
+          ready!
+        else
+          # This is the last step - finish the journey
+          logger.info { "skipping current step #{current_step_name}, finishing journey" }
+          finished!
+          update!(previous_step_name: current_step_name, next_step_name: nil)
+        end
       elsif finished?
         logger.info { "was marked finished inside the step" }
         update!(previous_step_name: current_step_name, next_step_name: nil)
@@ -247,6 +289,7 @@ module StepperMotor
       # and not via background jobs (which reload the model). This should actually be solved
       # using some object that contains the state of the action later, but for now - the dirty approach is fine.
       @reattempt_after = nil
+      @skip_current_step = nil
       @current_step_definition = nil
       # Re-raise the exception, now that we have persisted the Journey according to the recovery policy
       if ex_rescued_at_perform

data/lib/stepper_motor/step.rb

@@ -24,12 +24,39 @@ class StepperMotor::Step
   #   The possible values are:
   #   * `:cancel!` - cancels the Journey and re-raises the exception. The Journey will be persisted before re-raising.
   #   * `:reattempt!` - reattempts the Journey and re-raises the exception. The Journey will be persisted before re-raising.
-  def initialize(name:, seq:, on_exception:, wait: 0, &step_block)
+  #   * `:pause!` - pauses the Journey and re-raises the exception. The Journey will be persisted before re-raising.
+  #   * `:skip!` - skips the current step and proceeds to the next step, or finishes the journey if it's the last step.
+  # @param skip_if[TrueClass,FalseClass,NilClass,Symbol,Proc] condition to check before performing the step. If a boolean is provided,
+  #   it will be used directly. If nil is provided, it will be treated as false. If a symbol is provided,
+  #   it will call the method on the Journey. If a block is provided, it will be executed with the Journey as context.
+  #   The step will only be performed if the condition returns a truthy value.
+  def initialize(name:, seq:, on_exception: :pause!, wait: 0, skip_if: false, &step_block)
     @step_block = step_block
     @name = name.to_s
     @wait = wait
     @seq = seq
     @on_exception = on_exception # TODO: Validate?
+    @skip_if_condition = skip_if
+
+    # Validate the skip_if condition
+    if ![true, false, nil].include?(@skip_if_condition) && !@skip_if_condition.is_a?(Symbol) && !@skip_if_condition.respond_to?(:call)
+      raise ArgumentError, "skip_if: condition must be a boolean, nil, Symbol or a callable object, but was a #{@skip_if_condition.inspect}"
+    end
+  end
+
+  # Checks if the step should be skipped based on the skip_if condition
+  #
+  # @param journey[StepperMotor::Journey] the journey to check the condition for
+  # @return [Boolean] true if the step should be skipped, false otherwise
+  def should_skip?(journey)
+    case @skip_if_condition
+    when true, false, nil
+      !!@skip_if_condition
+    when Symbol
+      journey.send(@skip_if_condition) # Allow private methods
+    else
+      journey.instance_exec(&@skip_if_condition)
+    end
   end
 
   # Performs the step on the passed Journey, wrapping the step with the required context.
@@ -40,6 +67,12 @@ class StepperMotor::Step
   #   journey will be called
   # @return void
   def perform_in_context_of(journey)
+    # Return early should the `skip_if` condition be truthy
+    if should_skip?(journey)
+      journey.logger.info { "skipping as skip_if: condition was truthy" }
+      return
+    end
+
     # This is a tricky bit.
     #
     # reattempt!, cancel! (and potentially - future flow control methods) all use `throw` to
@@ -61,21 +94,18 @@ class StepperMotor::Step
       end
     end
   rescue MissingDefinition
-    # This journey won't succeed with any number of reattempts, cancel it. Cancellation also will throw.
+    # This journey won't succeed with any number of reattempts, pause it.
     catch(:abort_step) { journey.pause! }
     raise
   rescue => e
     # Act according to the set policy. The basic 2 for the moment are :reattempt! and :cancel!,
     # and can be applied by just calling the methods on the passed journey
     case @on_exception
-    when :reattempt!
-      catch(:abort_step) { journey.reattempt! }
-    when :cancel!
-      catch(:abort_step) { journey.cancel! }
-    when :pause!
-      catch(:abort_step) { journey.pause! }
+    when :reattempt!, :cancel!, :pause!, :skip!
+      catch(:abort_step) { journey.public_send(@on_exception) }
     else
       # Leave the journey hanging in the "performing" state
+      journey.logger.warn { "unusual on_exception: value (#{@on_exception.inspect}) - the journey will be left hanging in 'performing' state and will be collected as hung" }
     end
 
     # Re-raise the exception so that the Rails error handling can register it

data/lib/stepper_motor/version.rb

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