statesman 3.5.0 → 6.0.0

data/README.md

@@ -1,4 +1,4 @@
-![Statesman](http://f.cl.ly/items/410n2A0S3l1W0i3i0o2K/statesman.png)
+<p align="center"><img src="http://f.cl.ly/items/410n2A0S3l1W0i3i0o2K/statesman.png" alt="Statesman"></p>
 
 A statesmanlike state machine library.
 
@@ -30,7 +30,7 @@ protection.
 To get started, just add Statesman to your `Gemfile`, and then run `bundle`:
 
 ```ruby
-gem 'statesman', '~> 3.4.1'
+gem 'statesman', '~> 5.2.0'
 ```
 
 ## Usage
@@ -76,22 +76,16 @@ Then, link it to your model:
 
 ```ruby
 class Order < ActiveRecord::Base
-  include Statesman::Adapters::ActiveRecordQueries
-
   has_many :order_transitions, autosave: false
 
+  include Statesman::Adapters::ActiveRecordQueries[
+    transition_class: OrderTransition,
+    initial_state: :pending
+  ]
+
   def state_machine
     @state_machine ||= OrderStateMachine.new(self, transition_class: OrderTransition)
   end
-
-  def self.transition_class
-    OrderTransition
-  end
-
-  def self.initial_state
-    :pending
-  end
-  private_class_method :initial_state
 end
 ```
 
@@ -164,8 +158,9 @@ class Order < ActiveRecord::Base
   end
 
   # Optionally delegate some methods
-  delegate :can_transition_to?, :transition_to!, :transition_to, :current_state,
-           to: :state_machine
+
+  delegate :can_transition_to?, :current_state, :history, :last_transition,
+           :transition_to!, :transition_to, :in_state?, to: :state_machine
 end
 ```
 #### Using PostgreSQL JSON column
@@ -199,13 +194,11 @@ or 5. To do that
 ```ruby
 Statesman.configure do
   storage_adapter(Statesman::Adapters::ActiveRecord)
-  # ...or
-  storage_adapter(Statesman::Adapters::Mongoid)
 end
 ```
 Statesman defaults to storing transitions in memory. If you're using rails, you
 can instead configure it to persist transitions to the database by using the
-ActiveRecord or Mongoid adapter.
+ActiveRecord adapter.
 
 Statesman will fallback to memory unless you specify a transition_class when instantiating your state machine. This allows you to only persist transitions on certain state machines in your app.
 
@@ -234,7 +227,8 @@ end
 ```
 Define a guard. `to` and `from` parameters are optional, a nil parameter means
 guard all transitions. The passed block should evaluate to a boolean and must
-be idempotent as it could be called many times.
+be idempotent as it could be called many times. The guard will pass when it
+evaluates to a truthy value and fail when it evaluates to a falsey value (`nil` or `false`).
 
 #### `Machine.before_transition`
 ```ruby
@@ -261,6 +255,35 @@ after the transition.
 If you specify `after_commit: true`, the callback will be executed once the
 transition has been committed to the database.
 
+#### `Machine.after_transition_failure`
+```ruby
+Machine.after_transition_failure(from: :some_state, to: :another_state) do |object, exception|
+  Logger.info("transition to #{exception.to} failed for #{object.id}")
+end
+```
+Define a callback to run if `Statesman::TransitionFailedError` is raised
+during the execution of transition callbacks. `to` and `from`
+parameters are optional, a nil parameter means run after all transitions.
+The model object, and exception are passed as arguments to the callback.
+This is executed outside of the transaction wrapping other callbacks.
+If using `transition!` the exception is re-raised after these callbacks are
+executed.
+
+#### `Machine.after_guard_failure`
+```ruby
+Machine.after_guard_failure(from: :some_state, to: :another_state) do |object, exception|
+  Logger.info("guard failed during transition to #{exception.to} for #{object.id}")
+end
+```
+Define a callback to run if `Statesman::GuardFailedError` is raised
+during the execution of guard callbacks. `to` and `from`
+parameters are optional, a nil parameter means run after all transitions.
+The model object, and exception are passed as arguments to the callback.
+This is executed outside of the transaction wrapping other callbacks.
+If using `transition!` the exception is re-raised after these callbacks are
+executed.
+
+
 #### `Machine.new`
 ```ruby
 my_machine = Machine.new(my_model, transition_class: MyTransitionModel)
@@ -328,43 +351,34 @@ callback code throws an exception, it will not be caught.)
 
 A mixin is provided for the ActiveRecord adapter which adds scopes to easily
 find all models currently in (or not in) a given state. Include it into your
-model and define `transition_class` and `initial_state` class methods:
+model and passing in `transition_class` and `initial_state` as options.
+
+In 4.1.2 and below, these two options had to be defined as methods on the model,
+but 5.0.0 and above allow this style of configuration as well.
+The old method pollutes the model with extra class methods, and is deprecated,
+to be removed in 6.0.0.
 
 ```ruby
 class Order < ActiveRecord::Base
-  include Statesman::Adapters::ActiveRecordQueries
-
-  def self.transition_class
-    OrderTransition
-  end
-  private_class_method :transition_class
-
-  def self.initial_state
-    OrderStateMachine.initial_state
-  end
-  private_class_method :initial_state
+  has_many :order_transitions, autosave: false
+  include Statesman::Adapters::ActiveRecordQueries[
+    transition_class: OrderTransition,
+    initial_state: OrderStateMachine.initial_state
+  ]
 end
 ```
 
 If the transition class-name differs from the association name, you will also
-need to define a corresponding `transition_name` class method:
+need to pass `transition_name` as an option:
 
 ```ruby
 class Order < ActiveRecord::Base
   has_many :transitions, class_name: "OrderTransition", autosave: false
-
-  def self.transition_name
-    :transitions
-  end
-
-  def self.transition_class
-    OrderTransition
-  end
-
-  def self.initial_state
-    OrderStateMachine.initial_state
-  end
-  private_class_method :initial_state
+  include Statesman::Adapters::ActiveRecordQueries[
+    transition_class: OrderTransition,
+    initial_state: OrderStateMachine.initial_state,
+    transition_name: :transitions
+  ]
 end
 ```
 
@@ -375,7 +389,7 @@ Returns all models currently in any of the supplied states.
 Returns all models not currently in any of the supplied states.
 
 
-### `Model.most_recent_transition_join`
+#### `Model.most_recent_transition_join`
 This joins the model to its most recent transition whatever that may be.
 We expose this method to ease use of ActiveRecord's `or` e.g
 
@@ -406,7 +420,7 @@ You could also use a calculated column or view in your database.
 Given a field `foo` that was stored in the metadata, you can access it like so:
 
 ```ruby
-model_instance.last_transition.metadata["foo"]
+model_instance.state_machine.last_transition.metadata["foo"]
 ```
 
 #### Events
@@ -425,6 +439,22 @@ class OrderStateMachine
 end
 ```
 
+#### Deleting records.
+
+If you need to delete the Parent model regularly you will need to change
+either the association deletion behaviour or add a `DELETE CASCADE` condition
+to foreign key in your database.
+
+E.g
+```
+has_many :order_transitions, autosave: false, dependent: :destroy
+```
+or when migrating the transition model
+```
+add_foreign_key :order_transitions, :orders, on_delete: :cascade
+```
+
+
 ## Testing Statesman Implementations
 
 This answer was abstracted from [this issue](https://github.com/gocardless/statesman/issues/77).

data/Rakefile

@@ -1,13 +1,11 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec) do |task|
   task.rspec_opts = []
 
-  if ENV["EXCLUDE_MONGOID"]
-    task.rspec_opts += ["--tag ~mongo", "--exclude-pattern **/*mongo*"]
-  end
-
   if ENV["CIRCLECI"]
     task.rspec_opts += ["--format RspecJunitFormatter",
                         "--out /tmp/test-results/rspec.xml",

data/lib/generators/statesman/active_record_transition_generator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "rails/generators"
 require "generators/statesman/generator_helpers"
 

data/lib/generators/statesman/generator_helpers.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Statesman
   module GeneratorHelpers
     def class_name_option

data/lib/generators/statesman/migration_generator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "rails/generators"
 require "generators/statesman/generator_helpers"
 

data/lib/statesman/adapters/active_record.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "../exceptions"
 
 module Statesman
@@ -25,6 +27,7 @@ module Statesman
         elsif serialized && JSON_COLUMN_TYPES.include?(column_type)
           raise IncompatibleSerializationError, transition_class.name
         end
+
         @transition_class = transition_class
         @parent_model = parent_model
         @observer = observer
@@ -36,6 +39,7 @@ module Statesman
         create_transition(from.to_s, to.to_s, metadata)
       rescue ::ActiveRecord::RecordNotUnique => e
         raise TransitionConflictError, e.message if transition_conflict_error? e
+
         raise
       ensure
         @last_transition = nil
@@ -70,20 +74,28 @@ module Statesman
 
         transition = transitions_for_parent.build(transition_attributes)
 
-        ::ActiveRecord::Base.transaction do
+        ::ActiveRecord::Base.transaction(requires_new: true) do
           @observer.execute(:before, from, to, transition)
           unset_old_most_recent
           transition.save!
           @last_transition = transition
           @observer.execute(:after, from, to, transition)
+          add_after_commit_callback(from, to, transition)
         end
-        @observer.execute(:after_commit, from, to, transition)
 
         transition
       end
 
+      def add_after_commit_callback(from, to, transition)
+        ::ActiveRecord::Base.connection.add_transaction_record(
+          ActiveRecordAfterCommitWrap.new do
+            @observer.execute(:after_commit, from, to, transition)
+          end,
+        )
+      end
+
       def transitions_for_parent
-        @parent_model.send(@association_name)
+        parent_model.send(@association_name)
       end
 
       def unset_old_most_recent
@@ -118,10 +130,46 @@ module Statesman
       end
 
       def transition_conflict_error?(err)
-        err.message.include?(@transition_class.table_name) &&
+        return true if unique_indexes.any? { |i| err.message.include?(i.name) }
+
+        err.message.include?(transition_class.table_name) &&
           (err.message.include?("sort_key") || err.message.include?("most_recent"))
       end
 
+      def unique_indexes
+        ::ActiveRecord::Base.connection.
+          indexes(transition_class.table_name).
+          select do |index|
+            next unless index.unique
+
+            # We care about the columns used in the index, but not necessarily
+            # the order, which is why we sort both sides of the comparison here
+            index.columns.sort == [parent_join_foreign_key, "sort_key"].sort ||
+              index.columns.sort == [parent_join_foreign_key, "most_recent"].sort
+          end
+      end
+
+      def parent_join_foreign_key
+        association =
+          parent_model.class.
+            reflect_on_all_associations(:has_many).
+            find { |r| r.name.to_s == @association_name.to_s }
+
+        association_join_primary_key(association)
+      end
+
+      def association_join_primary_key(association)
+        if association.respond_to?(:join_primary_key)
+          association.join_primary_key
+        elsif association.method(:join_keys).arity.zero?
+          # Support for Rails 5.1
+          association.join_keys.key
+        else
+          # Support for Rails < 5.1
+          association.join_keys(transition_class).key
+        end
+      end
+
       def with_updated_timestamp(params)
         # TODO: Once we've set expectations that transition classes should conform to
         # the interface of Adapters::ActiveRecordTransition as a breaking change in the
@@ -130,8 +178,8 @@ module Statesman
         #
         # At the moment, most transition classes will include the module, but not all,
         # not least because it doesn't work with PostgreSQL JSON columns for metadata.
-        column = if @transition_class.respond_to?(:updated_timestamp_column)
-                   @transition_class.updated_timestamp_column
+        column = if transition_class.respond_to?(:updated_timestamp_column)
+                   transition_class.updated_timestamp_column
                  else
                    ActiveRecordTransition::DEFAULT_UPDATED_TIMESTAMP_COLUMN
                  end
@@ -147,5 +195,39 @@ module Statesman
         params.merge(column => timestamp)
       end
     end
+
+    class ActiveRecordAfterCommitWrap
+      def initialize
+        @callback = Proc.new
+        @connection = ::ActiveRecord::Base.connection
+      end
+
+      def self.trigger_transactional_callbacks?
+        true
+      end
+
+      def trigger_transactional_callbacks?
+        true
+      end
+
+      # rubocop: disable Naming/PredicateName
+      def has_transactional_callbacks?
+        true
+      end
+      # rubocop: enable Naming/PredicateName
+
+      def committed!(*)
+        @callback.call
+      end
+
+      def before_committed!(*); end
+
+      def rolledback!(*); end
+
+      # Required for +transaction(requires_new: true)+
+      def add_to_transaction(*)
+        @connection.add_transaction_record(self)
+      end
+    end
   end
 end

data/lib/statesman/adapters/active_record_queries.rb

@@ -1,51 +1,124 @@
+# frozen_string_literal: true
+
 module Statesman
   module Adapters
     module ActiveRecordQueries
+      def self.check_missing_methods!(base)
+        missing_methods = %i[transition_class initial_state].
+          reject { |m| base.respond_to?(m) }
+        return if missing_methods.none?
+
+        raise NotImplementedError,
+              "#{missing_methods.join(', ')} method(s) should be defined on " \
+              "the model. Alternatively, use the new form of `include " \
+              "Statesman::Adapters::ActiveRecordQueries[" \
+              "transition_class: MyTransition, " \
+              "initial_state: :some_state]`"
+      end
+
       def self.included(base)
-        base.extend(ClassMethods)
+        check_missing_methods!(base)
+
+        base.include(
+          ClassMethods.new(
+            transition_class: base.transition_class,
+            initial_state: base.initial_state,
+            most_recent_transition_alias: base.try(:most_recent_transition_alias),
+            transition_name: base.try(:transition_name),
+          ),
+        )
       end
 
-      module ClassMethods
-        def in_state(*states)
-          states = states.flatten.map(&:to_s)
+      def self.[](**args)
+        ClassMethods.new(**args)
+      end
 
-          joins(most_recent_transition_join).
-            where(states_where(most_recent_transition_alias, states), states)
+      class ClassMethods < Module
+        def initialize(**args)
+          @args = args
         end
 
-        def not_in_state(*states)
-          states = states.flatten.map(&:to_s)
+        def included(base)
+          ensure_inheritance(base)
 
-          joins(most_recent_transition_join).
-            where("NOT (#{states_where(most_recent_transition_alias, states)})",
-                  states)
-        end
+          query_builder = QueryBuilder.new(base, **@args)
 
-        def most_recent_transition_join
-          "LEFT OUTER JOIN #{model_table} AS #{most_recent_transition_alias}
-             ON #{table_name}.id =
-                  #{most_recent_transition_alias}.#{model_foreign_key}
-             AND #{most_recent_transition_alias}.most_recent = #{db_true}"
+          base.define_singleton_method(:most_recent_transition_join) do
+            query_builder.most_recent_transition_join
+          end
+
+          define_in_state(base, query_builder)
+          define_not_in_state(base, query_builder)
         end
 
         private
 
-        def transition_class
-          raise NotImplementedError, "A transition_class method should be " \
-                                     "defined on the model"
+        def ensure_inheritance(base)
+          klass = self
+          existing_inherited = base.method(:inherited)
+          base.define_singleton_method(:inherited) do |subclass|
+            existing_inherited.call(subclass)
+            subclass.send(:include, klass)
+          end
+        end
+
+        def define_in_state(base, query_builder)
+          base.define_singleton_method(:in_state) do |*states|
+            states = states.flatten
+
+            joins(most_recent_transition_join).
+              where(query_builder.states_where(states), states)
+          end
+        end
+
+        def define_not_in_state(base, query_builder)
+          base.define_singleton_method(:not_in_state) do |*states|
+            states = states.flatten
+
+            joins(most_recent_transition_join).
+              where("NOT (#{query_builder.states_where(states)})", states)
+          end
+        end
+      end
+
+      class QueryBuilder
+        def initialize(model, transition_class:, initial_state:,
+                       most_recent_transition_alias: nil,
+                       transition_name: nil)
+          @model = model
+          @transition_class = transition_class
+          @initial_state = initial_state
+          @most_recent_transition_alias = most_recent_transition_alias
+          @transition_name = transition_name
         end
 
-        def initial_state
-          raise NotImplementedError, "An initial_state method should be " \
-                                     "defined on the model"
+        def states_where(states)
+          if initial_state.to_s.in?(states.map(&:to_s))
+            "#{most_recent_transition_alias}.to_state IN (?) OR " \
+            "#{most_recent_transition_alias}.to_state IS NULL"
+          else
+            "#{most_recent_transition_alias}.to_state IN (?) AND " \
+            "#{most_recent_transition_alias}.to_state IS NOT NULL"
+          end
+        end
+
+        def most_recent_transition_join
+          "LEFT OUTER JOIN #{model_table} AS #{most_recent_transition_alias} " \
+             "ON #{model.table_name}.id = " \
+                  "#{most_recent_transition_alias}.#{model_foreign_key} " \
+             "AND #{most_recent_transition_alias}.most_recent = #{db_true}"
         end
 
+        private
+
+        attr_reader :model, :transition_class, :initial_state
+
         def transition_name
-          transition_class.table_name.to_sym
+          @transition_name || transition_class.table_name.to_sym
         end
 
         def transition_reflection
-          reflect_on_all_associations(:has_many).each do |value|
+          model.reflect_on_all_associations(:has_many).each do |value|
             return value if value.klass == transition_class
           end
 
@@ -62,18 +135,9 @@ module Statesman
           transition_reflection.table_name
         end
 
-        def states_where(temporary_table_name, states)
-          if initial_state.to_s.in?(states.map(&:to_s))
-            "#{temporary_table_name}.to_state IN (?) OR " \
-            "#{temporary_table_name}.to_state IS NULL"
-          else
-            "#{temporary_table_name}.to_state IN (?) AND " \
-            "#{temporary_table_name}.to_state IS NOT NULL"
-          end
-        end
-
         def most_recent_transition_alias
-          "most_recent_#{transition_name.to_s.singularize}"
+          @most_recent_transition_alias ||
+            "most_recent_#{transition_name.to_s.singularize}"
         end
 
         def db_true

data/lib/statesman/adapters/active_record_transition.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "json"
 
 module Statesman

data/lib/statesman/adapters/memory.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "json"
 
 module Statesman

data/lib/statesman/adapters/memory_transition.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Statesman
   module Adapters
     class MemoryTransition

data/lib/statesman/callback.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "exceptions"
 
 module Statesman

data/lib/statesman/config.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "json"
 require_relative "exceptions"
 

data/lib/statesman/exceptions.rb

@@ -1,9 +1,36 @@
+# frozen_string_literal: true
+
 module Statesman
   class InvalidStateError < StandardError; end
   class InvalidTransitionError < StandardError; end
   class InvalidCallbackError < StandardError; end
-  class GuardFailedError < StandardError; end
-  class TransitionFailedError < StandardError; end
+
+  class TransitionFailedError < StandardError
+    def initialize(from, to)
+      @from = from
+      @to = to
+    end
+
+    attr_reader :from, :to
+
+    def message
+      "Cannot transition from '#{from}' to '#{to}'"
+    end
+  end
+
+  class GuardFailedError < StandardError
+    def initialize(from, to)
+      @from = from
+      @to = to
+    end
+
+    attr_reader :from, :to
+
+    def message
+      "Guard on transition from: '#{from}' to '#{to}' returned false"
+    end
+  end
+
   class TransitionConflictError < StandardError; end
   class MissingTransitionAssociation < StandardError; end
 

data/lib/statesman/guard.rb

@@ -1,13 +1,12 @@
+# frozen_string_literal: true
+
 require_relative "callback"
 require_relative "exceptions"
 
 module Statesman
   class Guard < Callback
     def call(*args)
-      unless super(*args)
-        raise GuardFailedError,
-              "Guard on transition from: '#{from}' to '#{to}' returned false"
-      end
+      raise GuardFailedError.new(from, to) unless super(*args)
     end
   end
 end