state_machines 0.6.0 → 0.30.0

data/lib/state_machines/eval_helpers.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+require_relative 'syntax_validator'
+
 module StateMachines
   # Provides a set of helper methods for evaluating methods within the context
   # of an object.
@@ -50,37 +54,100 @@ module StateMachines
     #   evaluate_method(person, lambda {|person| person.name}, 21)                              # => "John Smith"
     #   evaluate_method(person, lambda {|person, age| "#{person.name} is #{age}"}, 21)          # => "John Smith is 21"
     #   evaluate_method(person, lambda {|person, age| "#{person.name} is #{age}"}, 21, 'male')  # => ArgumentError: wrong number of arguments (3 for 2)
-    def evaluate_method(object, method, *args, &block)
+    def evaluate_method(object, method, *args, **, &block)
       case method
-        when Symbol
-          klass = (class << object; self; end)
-          args = [] if (klass.method_defined?(method) || klass.private_method_defined?(method)) && object.method(method).arity == 0
-          object.send(method, *args, &block)
-        when Proc, Method
-          args.unshift(object)
-          arity = method.arity
-
-          # Procs don't support blocks in < Ruby 1.9, so it's tacked on as an
-          # argument for consistency across versions of Ruby
-          if block_given? && Proc === method && arity != 0
-            if [1, 2].include?(arity)
-              # Force the block to be either the only argument or the 2nd one
-              # after the object (may mean additional arguments get discarded)
-              args = args[0, arity - 1] + [block]
-            else
-              # Tack the block to the end of the args
-              args << block
-            end
+      when Symbol
+        klass = (class << object; self; end)
+        args = [] if (klass.method_defined?(method) || klass.private_method_defined?(method)) && object.method(method).arity == 0
+        object.send(method, *args, **, &block)
+      when Proc
+        args.unshift(object)
+        arity = method.arity
+        # Handle blocks for Procs
+        if block_given? && arity != 0
+          if [1, 2].include?(arity)
+            # Force the block to be either the only argument or the second one
+            # after the object (may mean additional arguments get discarded)
+            args = args[0, arity - 1] + [block]
           else
-            # These method types are only called with 0, 1, or n arguments
-            args = args[0, arity] if [0, 1].include?(arity)
+            # insert the block to the end of the args
+            args << block
           end
+        elsif [0, 1].include?(arity)
+          # These method types are only called with 0, 1, or n arguments
+          args = args[0, arity]
+        end
+
+        # Call the Proc with the arguments
+        method.call(*args, **)
 
-          method.is_a?(Proc) ? method.call(*args) : method.call(*args, &block)
-        when String
-          eval(method, object.instance_eval { binding }, &block)
+      when Method
+        args.unshift(object)
+        arity = method.arity
+
+        # Methods handle blocks via &block, not as arguments
+        # Only limit arguments if necessary based on arity
+        args = args[0, arity] if [0, 1].include?(arity)
+
+        # Call the Method with the arguments and pass the block
+        method.call(*args, **, &block)
+      when String
+        # Input validation for string evaluation
+        validate_eval_string(method)
+
+        if block_given?
+          if StateMachines::Transition.pause_supported?
+            eval(method, object.instance_eval { binding }, &block)
+          else
+            # Support for JRuby and Truffle Ruby, which don't support binding blocks
+            # Need to check with @headius, if jruby 10 does now.
+            eigen = class << object; self; end
+            eigen.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+                  def __temp_eval_method__(*args, &b)
+                    #{method}
+                  end
+            RUBY
+            result = object.__temp_eval_method__(*args, &block)
+            eigen.send(:remove_method, :__temp_eval_method__)
+            result
+          end
         else
-          raise ArgumentError, 'Methods must be a symbol denoting the method to call, a block to be invoked, or a string to be evaluated'
+          eval(method, object.instance_eval { binding })
+        end
+      else
+        raise ArgumentError, 'Methods must be a symbol denoting the method to call, a block to be invoked, or a string to be evaluated'
+      end
+    end
+
+    private
+
+    # Validates string input before eval to prevent code injection
+    # This is a basic safety check - not foolproof security
+    def validate_eval_string(method_string)
+      # Check for obviously dangerous patterns
+      dangerous_patterns = [
+        /`.*`/,           # Backticks (shell execution)
+        /system\s*\(/,    # System calls
+        /exec\s*\(/,      # Exec calls
+        /eval\s*\(/,      # Nested eval
+        /require\s+['"]/, # Require statements
+        /load\s+['"]/, # Load statements
+        /File\./,         # File operations
+        /IO\./,           # IO operations
+        /Dir\./,          # Directory operations
+        /Kernel\./        # Kernel operations
+      ]
+
+      dangerous_patterns.each do |pattern|
+        raise SecurityError, "Potentially dangerous code detected in eval string: #{method_string.inspect}" if method_string.match?(pattern)
+      end
+
+      # Basic syntax validation - but allow yield since it's valid in block context
+      begin
+        test_code = method_string.include?('yield') ? "def dummy_method; #{method_string}; end" : method_string
+        SyntaxValidator.validate!(test_code, '(eval)')
+      rescue SyntaxError => e
+        raise ArgumentError, "Invalid Ruby syntax in eval string: #{e.message}"
       end
     end
   end

data/lib/state_machines/event.rb

@@ -1,9 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'options_validator'
+
 module StateMachines
   # An event defines an action that transitions an attribute from one state to
   # another.  The state that an attribute is transitioned to depends on the
   # branches configured for the event.
   class Event
-
     include MatcherHelpers
 
     # The state machine for which this event is defined
@@ -30,13 +33,23 @@ module StateMachines
     #
     # Configuration options:
     # * <tt>:human_name</tt> - The human-readable version of this event's name
-    def initialize(machine, name, options = {}) #:nodoc:
-      options.assert_valid_keys(:human_name)
+    def initialize(machine, name, options = nil, human_name: nil, **extra_options) # :nodoc:
+      # Handle both old hash style and new kwargs style for backward compatibility
+      if options.is_a?(Hash)
+        # Old style: initialize(machine, name, {human_name: 'Custom Name'})
+        StateMachines::OptionsValidator.assert_valid_keys!(options, :human_name)
+        human_name = options[:human_name]
+      else
+        # New style: initialize(machine, name, human_name: 'Custom Name')
+        raise ArgumentError, "Unexpected positional argument: #{options.inspect}" unless options.nil?
+
+        StateMachines::OptionsValidator.assert_valid_keys!(extra_options, :human_name) unless extra_options.empty?
+      end
 
       @machine = machine
       @name = name
       @qualified_name = machine.namespace ? :"#{name}_#{machine.namespace}" : name
-      @human_name = options[:human_name] || @name.to_s.tr('_', ' ')
+      @human_name = human_name || @name.to_s.tr('_', ' ')
       reset
 
       # Output a warning if another event has a conflicting qualified name
@@ -50,7 +63,7 @@ module StateMachines
 
     # Creates a copy of this event in addition to the list of associated
     # branches to prevent conflicts across events within a class hierarchy.
-    def initialize_copy(orig) #:nodoc:
+    def initialize_copy(orig) # :nodoc:
       super
       @branches = @branches.dup
       @known_states = @known_states.dup
@@ -64,8 +77,8 @@ module StateMachines
 
     # Evaluates the given block within the context of this event.  This simply
     # provides a DSL-like syntax for defining transitions.
-    def context(&block)
-      instance_eval(&block)
+    def context(&)
+      instance_eval(&)
     end
 
     # Creates a new transition that determines what to change the current state
@@ -89,7 +102,7 @@ module StateMachines
 
       # Only a certain subset of explicit options are allowed for transition
       # requirements
-      options.assert_valid_keys(:from, :to, :except_from, :except_to, :if, :unless) if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on, :if, :unless]).empty?
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :from, :to, :except_from, :except_to, :if, :unless) if (options.keys - %i[from to on except_from except_to except_on if unless]).empty?
 
       branches << branch = Branch.new(options.merge(on: name))
       @known_states |= branch.known_states
@@ -119,23 +132,23 @@ module StateMachines
     # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
     #   conditionals defined for each one.  Default is true.
     def transition_for(object, requirements = {})
-      requirements.assert_valid_keys(:from, :to, :guard)
+      StateMachines::OptionsValidator.assert_valid_keys!(requirements, :from, :to, :guard)
       requirements[:from] = machine.states.match!(object).name unless (custom_from_state = requirements.include?(:from))
 
       branches.each do |branch|
-        if (match = branch.match(object, requirements))
-          # Branch allows for the transition to occur
-          from = requirements[:from]
-          to = if match[:to].is_a?(LoopbackMatcher)
-                 from
-               else
-                 values = requirements.include?(:to) ? [requirements[:to]].flatten : [from] | machine.states.map { |state| state.name }
-
-                 match[:to].filter(values).first
-               end
-
-          return Transition.new(object, machine, name, from, to, !custom_from_state)
-        end
+        next unless (match = branch.match(object, requirements))
+
+        # Branch allows for the transition to occur
+        from = requirements[:from]
+        to = if match[:to].is_a?(LoopbackMatcher)
+               from
+             else
+               values = requirements.include?(:to) ? [requirements[:to]].flatten : [from] | machine.states.map { |state| state.name }
+
+               match[:to].filter(values).first
+             end
+
+        return Transition.new(object, machine, name, from, to, !custom_from_state)
       end
 
       # No transition matched
@@ -148,13 +161,13 @@ module StateMachines
     #
     # Any additional arguments are passed to the StateMachines::Transition#perform
     # instance method.
-    def fire(object, *args)
+    def fire(object, *)
       machine.reset(object)
 
       if (transition = transition_for(object))
-        transition.perform(*args)
+        transition.perform(*)
       else
-        on_failure(object, *args)
+        on_failure(object, *)
         false
       end
     end
@@ -179,9 +192,8 @@ module StateMachines
       @known_states = []
     end
 
-
-    def draw(graph, options = {})
-      fail NotImplementedError
+    def draw(graph, options = {}, io = $stdout)
+      machine.renderer.draw_event(self, graph, options, io)
     end
 
     # Generates a nicely formatted description of this event's contents.
@@ -201,7 +213,7 @@ module StateMachines
       "#<#{self.class} name=#{name.inspect} transitions=[#{transitions * ', '}]>"
     end
 
-  protected
+    protected
 
     # Add the various instance methods that can transition the object using
     # the current event

data/lib/state_machines/event_collection.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 module StateMachines
   # Represents a collection of events in a state machine
   class EventCollection < NodeCollection
-    def initialize(machine) #:nodoc:
-      super(machine, index: [:name, :qualified_name])
+    def initialize(machine) # :nodoc:
+      super(machine, index: %i[name qualified_name])
     end
 
     # Gets the list of events that can be fired on the given object.
@@ -128,12 +130,11 @@ module StateMachines
                                                      false
                                                    end
                                                  end
-
     end
 
-  private
+    private
 
-    def match(requirements) #:nodoc:
+    def match(requirements) # :nodoc:
       requirements && requirements[:on] ? [fetch(requirements.delete(:on))] : self
     end
   end

data/lib/state_machines/extensions.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 module StateMachines
   module ClassMethods
-    def self.extended(base) #:nodoc:
+    def self.extended(base) # :nodoc:
       base.class_eval do
         @state_machines = MachineCollection.new
       end
@@ -136,13 +138,13 @@ module StateMachines
     #   vehicle.fire_events!(:ignite, :disable_alarm) # => StateMachines::InvalidParallelTransition: Cannot run events in parallel: ignite, disable_alarm
     def fire_events!(*events)
       run_action = [true, false].include?(events.last) ? events.pop : true
-      fire_events(*(events + [run_action])) || fail(StateMachines::InvalidParallelTransition.new(self, events))
+      fire_events(*(events + [run_action])) || raise(StateMachines::InvalidParallelTransition.new(self, events))
     end
 
-  protected
+    protected
 
-    def initialize_state_machines(options = {}, &block) #:nodoc:
-      self.class.state_machines.initialize_states(self, options, &block)
+    def initialize_state_machines(options = {}, &) # :nodoc:
+      self.class.state_machines.initialize_states(self, options, &)
     end
   end
 end

data/lib/state_machines/helper_module.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module StateMachines
   # Represents a type of module that defines instance / class methods for a
   # state machine
-  class HelperModule < Module #:nodoc:
+  class HelperModule < Module # :nodoc:
     def initialize(machine, kind)
       @machine = machine
       @kind = kind

data/lib/state_machines/integrations/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module StateMachines
   module Integrations
     # Provides a set of base helpers for managing individual integrations
@@ -33,7 +35,7 @@ module StateMachines
         end
       end
 
-      def self.included(base) #:nodoc:
+      def self.included(base) # :nodoc:
         base.extend ClassMethods
       end
     end

data/lib/state_machines/integrations.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module StateMachines
   # Integrations allow state machines to take advantage of features within the
   # context of a particular library.  This is currently most useful with
@@ -24,15 +26,15 @@ module StateMachines
       #  Register integration
       def register(name_or_module)
         case name_or_module.class.to_s
-          when 'Module'
-            add(name_or_module)
-          else
-            fail IntegrationError
+        when 'Module'
+          add(name_or_module)
+        else
+          raise IntegrationError
         end
         true
       end
 
-      def reset #:nodoc:#
+      def reset # :nodoc:#
         @integrations = []
       end
 
@@ -45,12 +47,9 @@ module StateMachines
       #   StateMachines::Integrations.register(StateMachines::Integrations::ActiveModel)
       #   StateMachines::Integrations.integrations
       #   # => [StateMachines::Integrations::ActiveModel]
-      def integrations
-        # Register all namespaced integrations
-        @integrations
-      end
+      attr_reader :integrations
 
-      alias_method :list, :integrations
+      alias list integrations
 
       # Attempts to find an integration that matches the given class.  This will
       # look through all of the built-in integrations under the StateMachines::Integrations
@@ -100,12 +99,12 @@ module StateMachines
         integrations.detect { |integration| integration.integration_name == name } || raise(IntegrationNotFound.new(name))
       end
 
-    private
+      private
 
       def add(integration)
-        if integration.respond_to?(:integration_name)
-          @integrations.insert(0, integration) unless @integrations.include?(integration)
-        end
+        return unless integration.respond_to?(:integration_name)
+
+        @integrations.insert(0, integration) unless @integrations.include?(integration)
       end
     end
   end

data/lib/state_machines/machine/action_hooks.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module ActionHooks
+      protected
+
+      # Determines whether action helpers should be defined for this machine.
+      # This is only true if there is an action configured and no other machines
+      # have process this same configuration already.
+      def define_action_helpers?
+        action && owner_class.state_machines.none? { |_name, machine| machine.action == action && machine != self }
+      end
+
+      # Adds helper methods for automatically firing events when an action
+      # is invoked
+      def define_action_helpers
+        return unless action_hook
+
+        @action_hook_defined = true
+        define_action_hook
+      end
+
+      # Hooks directly into actions by defining the same method in an included
+      # module.  As a result, when the action gets invoked, any state events
+      # defined for the object will get run.  Method visibility is preserved.
+      def define_action_hook
+        action_hook = self.action_hook
+        action = self.action
+        private_action_hook = owner_class.private_method_defined?(action_hook)
+
+        # Only define helper if it hasn't
+        define_helper :instance, <<-END_EVAL, __FILE__, __LINE__ + 1
+            def #{action_hook}(*)
+              self.class.state_machines.transitions(self, #{action.inspect}).perform { super }
+            end
+
+            private #{action_hook.inspect} if #{private_action_hook}
+        END_EVAL
+      end
+
+      # The method to hook into for triggering transitions when invoked.  By
+      # default, this is the action configured for the machine.
+      #
+      # Since the default hook technique relies on module inheritance, the
+      # action must be defined in an ancestor of the owner classs in order for
+      # it to be the action hook.
+      def action_hook
+        action && owner_class_ancestor_has_method?(:instance, action) ? action : nil
+      end
+    end
+  end
+end

data/lib/state_machines/machine/callbacks.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module Callbacks
+      # Creates a callback that will be invoked *before* a transition is
+      # performed so long as the given requirements match the transition.
+      def before_transition(*args, **options, &)
+        # Extract legacy positional arguments and merge with keyword options
+        parsed_options = parse_callback_arguments(args, options)
+
+        # Only validate callback-specific options, not state transition requirements
+        callback_options = parsed_options.slice(:do, :if, :unless, :bind_to_object, :terminator)
+        StateMachines::OptionsValidator.assert_valid_keys!(callback_options, :do, :if, :unless, :bind_to_object, :terminator)
+
+        add_callback(:before, parsed_options, &)
+      end
+
+      # Creates a callback that will be invoked *after* a transition is
+      # performed so long as the given requirements match the transition.
+      def after_transition(*args, **options, &)
+        # Extract legacy positional arguments and merge with keyword options
+        parsed_options = parse_callback_arguments(args, options)
+
+        # Only validate callback-specific options, not state transition requirements
+        callback_options = parsed_options.slice(:do, :if, :unless, :bind_to_object, :terminator)
+        StateMachines::OptionsValidator.assert_valid_keys!(callback_options, :do, :if, :unless, :bind_to_object, :terminator)
+
+        add_callback(:after, parsed_options, &)
+      end
+
+      # Creates a callback that will be invoked *around* a transition so long
+      # as the given requirements match the transition.
+      def around_transition(*args, **options, &)
+        # Extract legacy positional arguments and merge with keyword options
+        parsed_options = parse_callback_arguments(args, options)
+
+        # Only validate callback-specific options, not state transition requirements
+        callback_options = parsed_options.slice(:do, :if, :unless, :bind_to_object, :terminator)
+        StateMachines::OptionsValidator.assert_valid_keys!(callback_options, :do, :if, :unless, :bind_to_object, :terminator)
+
+        add_callback(:around, parsed_options, &)
+      end
+
+      # Creates a callback that will be invoked after a transition has failed
+      # to be performed.
+      def after_failure(*args, **options, &)
+        # Extract legacy positional arguments and merge with keyword options
+        parsed_options = parse_callback_arguments(args, options)
+
+        # Only validate callback-specific options, not state transition requirements
+        callback_options = parsed_options.slice(:do, :if, :unless, :bind_to_object, :terminator)
+        StateMachines::OptionsValidator.assert_valid_keys!(callback_options, :do, :if, :unless, :bind_to_object, :terminator)
+
+        add_callback(:failure, parsed_options, &)
+      end
+    end
+  end
+end

data/lib/state_machines/machine/class_methods.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module ClassMethods
+      # Attempts to find or create a state machine for the given class.  For
+      # example,
+      #
+      #   StateMachines::Machine.find_or_create(Vehicle)
+      #   StateMachines::Machine.find_or_create(Vehicle, :initial => :parked)
+      #   StateMachines::Machine.find_or_create(Vehicle, :status)
+      #   StateMachines::Machine.find_or_create(Vehicle, :status, :initial => :parked)
+      #
+      # If a machine of the given name already exists in one of the class's
+      # superclasses, then a copy of that machine will be created and stored
+      # in the new owner class (the original will remain unchanged).
+      def find_or_create(owner_class, *args, &)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        name = args.first || :state
+
+        # Find an existing machine
+        machine = (owner_class.respond_to?(:state_machines) &&
+                  ((args.first && owner_class.state_machines[name]) || (!args.first &&
+                  owner_class.state_machines.values.first))) || nil
+
+        if machine
+          # Only create a new copy if changes are being made to the machine in
+          # a subclass
+          if machine.owner_class != owner_class && (options.any? || block_given?)
+            machine = machine.clone
+            machine.initial_state = options[:initial] if options.include?(:initial)
+            machine.owner_class = owner_class
+          end
+
+          # Evaluate DSL
+          machine.instance_eval(&) if block_given?
+        else
+          # No existing machine: create a new one
+          machine = new(owner_class, name, options, &)
+        end
+
+        machine
+      end
+
+      def draw(*)
+        raise NotImplementedError
+      end
+
+      # Default messages to use for validation errors in ORM integrations
+      # Thread-safe access via atomic operations on simple values
+      attr_accessor :ignore_method_conflicts
+
+      def default_messages
+        @default_messages ||= {
+          invalid: 'is invalid',
+          invalid_event: 'cannot transition when %s',
+          invalid_transition: 'cannot transition via "%1$s"'
+        }.freeze
+      end
+
+      def default_messages=(messages)
+        # Atomic replacement with frozen object
+        @default_messages = deep_freeze_hash(messages)
+      end
+
+      def replace_messages(message_hash)
+        # Atomic replacement: read current messages, merge with new ones, replace atomically
+        current_messages = @default_messages || {}
+        merged_messages = current_messages.merge(message_hash)
+        @default_messages = deep_freeze_hash(merged_messages)
+      end
+
+      attr_writer :renderer
+
+      def renderer
+        return @renderer if @renderer
+
+        STDIORenderer
+      end
+
+      private
+
+      # Deep freezes a hash and all its string values for thread safety
+      def deep_freeze_hash(hash)
+        hash.each_with_object({}) do |(key, value), frozen_hash|
+          frozen_key = key.respond_to?(:freeze) ? key.freeze : key
+          frozen_value = value.respond_to?(:freeze) ? value.freeze : value
+          frozen_hash[frozen_key] = frozen_value
+        end.freeze
+      end
+    end
+  end
+end