statesman 7.4.0 → 8.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0dbcc9fe3c29e715be585f2ddae96bdea9b80ca104daf00ee3378feab681b8e
-  data.tar.gz: c5824ece991650b8e6e979a9899dbdabc38b18209a79260f2aa9e9f4fda67da2
+  metadata.gz: 3d099ca7f60641163125a158ca189d41b571a46e4da8d5277a9391ff12df69e4
+  data.tar.gz: 5a33e698ded14cbc080f6d3e385d4d00d8191b5d1887e0b4fb062d592a35214f
 SHA512:
-  metadata.gz: 98fe2966e48e912b33f1c6d842aa6090782dd32be726532d8178377ffb0f1a551ee3d83eee291de0723c756eb0b1bda65dae73d695a47f8b6bd38106b127615f
-  data.tar.gz: 6be77a7114e2c3d59e76cfa71de583213ead8a171c5039941698c1e4b0b28b68500acba91d498fb488d33d0e31b3274fa5e373ce81a55f9f70e8e229132de1cf
+  metadata.gz: 1b7e63cd44278ca20c9aac95b6ff1372b83131d5df988b72d6fabfbbc98057917f33bc6cdbc447c2d1d04f075ac215e58eb5e0beb09d0fd7d2d16e672cebacd2
+  data.tar.gz: 63588d5869538bab0f4a7900f2761ed3bcfb124895485d2fc1667ec159763e4fad69327af25d7221f113f6c43396aabb3d8548085d6bb25229487c5d19ba11c0

data/.circleci/config.yml

@@ -86,34 +86,6 @@ jobs:
           - POSTGRES_DB=statesman_test
           - POSTGRES_PASSWORD=statesman
     steps: *steps
-  build-ruby265-rails-master-mysql:
-    docker:
-      - image: circleci/ruby:2.6.5-node
-        environment:
-          - RAILS_VERSION=master
-          - DATABASE_URL=mysql2://root@127.0.0.1/statesman_test
-          - DATABASE_DEPENDENCY_PORT=3306
-      - image: circleci/mysql:5.7.18
-        environment:
-          - MYSQL_ALLOW_EMPTY_PASSWORD=true
-          - MYSQL_USER=root
-          - MYSQL_PASSWORD=
-          - MYSQL_DATABASE=statesman_test
-    steps: *steps
-  build-ruby265-rails-master-postgres:
-    docker:
-      - image: circleci/ruby:2.6.5-node
-        environment:
-          - RAILS_VERSION=master
-          - DATABASE_URL=postgres://postgres@localhost/statesman_test
-          - EXCLUDE_MONGOID=true
-          - DATABASE_DEPENDENCY_PORT=5432
-      - image: circleci/postgres:9.6
-        environment:
-          - POSTGRES_USER=postgres
-          - POSTGRES_DB=statesman_test
-          - POSTGRES_PASSWORD=statesman
-    steps: *steps
 
   build-ruby270-rails-602-mysql:
     docker:
@@ -142,11 +114,11 @@ jobs:
           - POSTGRES_DB=statesman_test
           - POSTGRES_PASSWORD=statesman
     steps: *steps
-  build-ruby270-rails-master-mysql:
+  build-ruby270-rails-main-mysql:
     docker:
       - image: circleci/ruby:2.7.0-node
         environment:
-          - RAILS_VERSION=master
+          - RAILS_VERSION=main
           - DATABASE_URL=mysql2://root@127.0.0.1/statesman_test
           - DATABASE_DEPENDENCY_PORT=3306
       - image: circleci/mysql:5.7.18
@@ -156,11 +128,11 @@ jobs:
           - MYSQL_PASSWORD=
           - MYSQL_DATABASE=statesman_test
     steps: *steps
-  build-ruby270-rails-master-postgres:
+  build-ruby270-rails-main-postgres:
     docker:
       - image: circleci/ruby:2.7.0-node
         environment:
-          - RAILS_VERSION=master
+          - RAILS_VERSION=main
           - DATABASE_URL=postgres://postgres@localhost/statesman_test
           - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=5432
@@ -179,9 +151,7 @@ workflows:
       - build-ruby249-rails-524-postgres
       - build-ruby265-rails-602-mysql
       - build-ruby265-rails-602-postgres
-      - build-ruby265-rails-master-mysql
-      - build-ruby265-rails-master-postgres
       - build-ruby270-rails-602-mysql
       - build-ruby270-rails-602-postgres
-      - build-ruby270-rails-master-mysql
-      - build-ruby270-rails-master-postgres
+      - build-ruby270-rails-main-mysql
+      - build-ruby270-rails-main-postgres

data/CHANGELOG.md

@@ -1,3 +1,38 @@
+## UNRELEASED
+
+### Added
+- Implement `Machine#last_transition_to`, to find the last transition to a given state
+  [#xxx](https://github.com/gocardless/statesman/pull/xxx)
+
+## v8.0.2 30th March 2021
+
+### Changed
+
+- Fixed a bug where the `history` of a model was left in an incorrect state after a transition
+  conflict [#433](https://github.com/gocardless/statesman/pull/433)
+
+## v8.0.1 20th January 2021
+
+### Changed
+
+- Fixed `no implicit conversion of nil into String` error when quoting null values
+  [#427](https://github.com/gocardless/statesman/pull/427)
+
+## v8.0.0 6th January 2021
+
+### Added
+
+- Use AR Arel table to type cast booleans in order to avoid deprecation warning [#421](https://github.com/gocardless/statesman/pull/421)
+- Support relationships that doesn't use `id` as a Primary Key
+  [#422](https://github.com/gocardless/statesman/pull/422)
+
+## v7.4.1 11th November 2020
+
+### Added
+
+- Add #reset method to state machine and adapter interfaces
+  [#417](https://github.com/gocardless/statesman/pull/417)
+
 ## v7.4.0 26th August 2020
 
 ### Added
@@ -9,16 +44,16 @@
 
 ### Changed
 
-- Use correct Arel for null [#409](https://github.com/gocardless/statesman/pull/#409)
+- Use correct Arel for null [#409](https://github.com/gocardless/statesman/pull/409)
 
 ## v7.2.0, 19th May 2020
 
 ### Changed
 
-- Set non-empty password for postgres tests [#398](https://github.com/gocardless/statesman/pull/#398)
-- Handle transitions differently for MySQL [#399](https://github.com/gocardless/statesman/pull/#399)
-- pg requirement from >= 0.18, <= 1.1 to >= 0.18, <= 1.3 [#400](https://github.com/gocardless/statesman/pull/#400)
-- Lazily enable mysql gaplock protection [#402](https://github.com/gocardless/statesman/pull/#402)
+- Set non-empty password for postgres tests [#398](https://github.com/gocardless/statesman/pull/398)
+- Handle transitions differently for MySQL [#399](https://github.com/gocardless/statesman/pull/399)
+- pg requirement from >= 0.18, <= 1.1 to >= 0.18, <= 1.3 [#400](https://github.com/gocardless/statesman/pull/400)
+- Lazily enable mysql gaplock protection [#402](https://github.com/gocardless/statesman/pull/402)
 
 ## v7.1.0, 10th Feb 2020
 
@@ -71,7 +106,7 @@
   to
   ```ruby
     include Statesman::Adapters::ActiveRecordQueries[
-      initial_state: :inital,
+      initial_state: :initial,
       transition_class: MyTransition
     ]
   ```

data/Gemfile

@@ -5,8 +5,8 @@ source 'https://rubygems.org'
 gemspec
 
 # rubocop:disable Bundler/DuplicatedGem
-if ENV['RAILS_VERSION'] == 'master'
-  gem "rails", git: "https://github.com/rails/rails"
+if ENV['RAILS_VERSION'] == 'main'
+  gem "rails", git: "https://github.com/rails/rails", branch: "main"
 elsif ENV['RAILS_VERSION']
   gem "rails", "~> #{ENV['RAILS_VERSION']}"
 end

data/README.md

@@ -1,4 +1,4 @@
-<p align="center"><img src="http://f.cl.ly/items/410n2A0S3l1W0i3i0o2K/statesman.png" alt="Statesman"></p>
+<p align="center"><img src="https://user-images.githubusercontent.com/110275/106792848-96e4ee80-664e-11eb-8fd1-16ff24b41eb2.png" alt="Statesman" width="512"></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', '~> 7.1.0'
+gem 'statesman', '~> 8.0.3'
 ```
 
 ## Usage
@@ -109,6 +109,8 @@ Order.first.state_machine.allowed_transitions # => ["checking_out", "cancelled"]
 Order.first.state_machine.can_transition_to?(:cancelled) # => true/false
 Order.first.state_machine.transition_to(:cancelled, optional: :metadata) # => true/false
 Order.first.state_machine.transition_to!(:cancelled) # => true/exception
+Order.first.state_machine.last_transition # => transition model or nil
+Order.first.state_machine.last_transition_to(:pending) # => transition model or nil
 
 Order.in_state(:cancelled) # => [#<Order id: "123">]
 Order.not_in_state(:checking_out) # => [#<Order id: "123">]
@@ -159,7 +161,8 @@ class Order < ActiveRecord::Base
 
   # Optionally delegate some methods
 
-  delegate :can_transition_to?, :current_state, :history, :last_transition,
+  delegate :can_transition_to?,
+           :current_state, :history, :last_transition, :last_transition_to,
            :transition_to!, :transition_to, :in_state?, to: :state_machine
 end
 ```
@@ -322,6 +325,10 @@ Machine.successors
 #### `Machine#current_state`
 Returns the current state based on existing transition objects.
 
+Takes an optional keyword argument to force a reload of data from the
+database.
+e.g `current_state(force_reload: true)`
+
 #### `Machine#in_state?(:state_1, :state_2, ...)`
 Returns true if the machine is in any of the given states.
 
@@ -331,6 +338,9 @@ Returns a sorted array of all transition objects.
 #### `Machine#last_transition`
 Returns the most recent transition object.
 
+#### `Machine#last_transition_to(:state)`
+Returns the most recent transition object to a given state.
+
 #### `Machine#allowed_transitions`
 Returns an array of states you can `transition_to` from current state.
 
@@ -347,6 +357,66 @@ Transition to the passed state, returning `true` on success. Swallows all
 Statesman exceptions and returns false on failure. (NB. if your guard or
 callback code throws an exception, it will not be caught.)
 
+
+## Errors
+
+### Initialization errors
+These errors are raised when the Machine and/or Model is initialized. A simple spec like
+```ruby
+expect { OrderStateMachine.new(Order.new, transition_class: OrderTransition) }.to_not raise_error
+```
+will expose these errors as part of your test suite
+
+#### InvalidStateError
+Raised if:
+  * Attempting to define a transition without a `to` state.
+  * Attempting to define a transition with a non-existent state.
+  * Attempting to define multiple states as `initial`.
+
+#### InvalidTransitionError
+Raised if:
+  * Attempting to define a callback `from` a state that has no valid transitions (A terminal state).
+  * Attempting to define a callback `to` the `initial` state if that state has no transitions to it.
+  * Attempting to define a callback with `from` and `to` where any of the pairs have no transition between them.
+
+#### InvalidCallbackError
+Raised if:
+  * Attempting to define a callback without a block.
+
+#### UnserializedMetadataError
+Raised if:
+  * ActiveRecord is configured to not serialize the `metadata` attribute into
+    to Database column backing it. See the `Using PostgreSQL JSON column` section.
+
+#### IncompatibleSerializationError
+Raised if:
+  * There is a mismatch between the column type of the `metadata` in the
+    Database and the model. See the `Using PostgreSQL JSON column` section.
+
+#### MissingTransitionAssociation
+Raised if:
+  * The model that `Statesman::Adapters::ActiveRecordQueries` is included in
+    does not have a `has_many` association to the `transition_class`.
+
+### Runtime errors
+These errors are raised by `transition_to!`. Using `transition_to` will
+supress `GuardFailedError` and `TransitionFailedError` and return `false` instead.
+
+#### GuardFailedError
+Raised if:
+  * A guard callback between `from` and `to` state returned a falsey value.
+
+#### TransitionFailedError
+Raised if:
+  * A transition is attempted but `current_state -> new_state` is not a valid pair.
+
+#### TransitionConflictError
+Raised if:
+  * A database conflict affecting the `sort_key` or `most_recent` columns occurs
+    when attempting a transition.
+    Retried automatically if it occurs wrapped in `retry_conflicts`.
+
+
 ## Model scopes
 
 A mixin is provided for the ActiveRecord adapter which adds scopes to easily
@@ -404,10 +474,12 @@ Model.in_state(:state_1).or(
 #### Storing the state on the model object
 
 If you wish to store the model state on the model directly, you can keep it up
-to date using an `after_transition` hook:
+to date using an `after_transition` hook.
+Combine it with the `after_commit` option to ensure the model state will only be
+saved once the transition has made it irreversibly to the database:
 
 ```ruby
-after_transition do |model, transition|
+after_transition(after_commit: true) do |model, transition|
   model.state = transition.to_state
   model.save!
 end

data/lib/generators/statesman/generator_helpers.rb

@@ -39,8 +39,16 @@ module Statesman
     end
 
     def mysql?
-      ActiveRecord::Base.configurations[Rails.env].
-        try(:[], "adapter").try(:match, /mysql/)
+      configuration.try(:[], "adapter").try(:match, /mysql/)
+    end
+
+    # [] is deprecated and will be removed in 6.2
+    def configuration
+      if ActiveRecord::Base.configurations.respond_to?(:configs_for)
+        ActiveRecord::Base.configurations.configs_for(env_name: Rails.env).first
+      else
+        ActiveRecord::Base.configurations[Rails.env]
+      end
     end
 
     def database_supports_partial_indexes?

data/lib/statesman/adapters/active_record.rb

@@ -42,7 +42,13 @@ module Statesman
       def create(from, to, metadata = {})
         create_transition(from.to_s, to.to_s, metadata)
       rescue ::ActiveRecord::RecordNotUnique => e
-        raise TransitionConflictError, e.message if transition_conflict_error? e
+        if transition_conflict_error? e
+          # The history has the invalid transition on the end of it, which means
+          # `current_state` would then be incorrect. We force a reload of the history to
+          # avoid this.
+          transitions_for_parent.reload
+          raise TransitionConflictError, e.message
+        end
 
         raise
       ensure
@@ -67,6 +73,10 @@ module Statesman
         end
       end
 
+      def reset
+        @last_transition = nil
+      end
+
       private
 
       # rubocop:disable Metrics/MethodLength
@@ -301,25 +311,23 @@ module Statesman
       end
 
       def db_true
-        value = ::ActiveRecord::Base.connection.type_cast(
-          true,
-          transition_class.columns_hash["most_recent"],
-        )
-        ::ActiveRecord::Base.connection.quote(value)
+        ::ActiveRecord::Base.connection.quote(type_cast(true))
       end
 
       def db_false
-        value = ::ActiveRecord::Base.connection.type_cast(
-          false,
-          transition_class.columns_hash["most_recent"],
-        )
-        ::ActiveRecord::Base.connection.quote(value)
+        ::ActiveRecord::Base.connection.quote(type_cast(false))
       end
 
       def db_null
         Arel::Nodes::SqlLiteral.new("NULL")
       end
 
+      # Type casting against a column is deprecated and will be removed in Rails 6.2.
+      # See https://github.com/rails/arel/commit/6160bfbda1d1781c3b08a33ec4955f170e95be11
+      def type_cast(value)
+        ::ActiveRecord::Base.connection.type_cast(value)
+      end
+
       # Check whether the `most_recent` column allows null values. If it doesn't, set old
       # records to `false`, otherwise, set them to `NULL`.
       #

data/lib/statesman/adapters/active_record_queries.rb

@@ -104,7 +104,7 @@ module Statesman
 
         def most_recent_transition_join
           "LEFT OUTER JOIN #{model_table} AS #{most_recent_transition_alias} " \
-             "ON #{model.table_name}.id = " \
+             "ON #{model.table_name}.#{model_primary_key} = " \
                   "#{most_recent_transition_alias}.#{model_foreign_key} " \
              "AND #{most_recent_transition_alias}.most_recent = #{db_true}"
         end
@@ -127,6 +127,10 @@ module Statesman
                 "and #{transition_class}."
         end
 
+        def model_primary_key
+          transition_reflection.active_record_primary_key
+        end
+
         def model_foreign_key
           transition_reflection.foreign_key
         end

data/lib/statesman/adapters/memory.rb

@@ -37,6 +37,10 @@ module Statesman
         @history
       end
 
+      def reset
+        @history = []
+      end
+
       private
 
       def next_sort_key

data/lib/statesman/machine.rb

@@ -209,6 +209,10 @@ module Statesman
       @storage_adapter.last(force_reload: force_reload)
     end
 
+    def last_transition_to(state)
+      history.reverse.find { |transition| transition.to_state.to_sym == state.to_sym }
+    end
+
     def can_transition_to?(new_state, metadata = {})
       validate_transition(from: current_state,
                           to: new_state,
@@ -257,6 +261,10 @@ module Statesman
       false
     end
 
+    def reset
+      @storage_adapter.reset
+    end
+
     private
 
     def adapter_class(transition_class)

data/lib/statesman/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Statesman
-  VERSION = "7.4.0"
+  VERSION = "8.0.3"
 end

data/spec/statesman/adapters/active_record_queries_spec.rb

@@ -154,6 +154,31 @@ describe Statesman::Adapters::ActiveRecordQueries, active_record: true do
       end
     end
 
+    context "with a custom primary key for the model" do
+      before do
+        # Switch to using OtherActiveRecordModelTransition, so the existing
+        # relation with MyActiveRecordModelTransition doesn't interfere with
+        # this spec.
+        # Configure the relationship to use a different primary key,
+        MyActiveRecordModel.send(:has_many,
+                                 :custom_name,
+                                 class_name: "OtherActiveRecordModelTransition",
+                                 primary_key: :external_id)
+
+        MyActiveRecordModel.class_eval do
+          def self.transition_class
+            OtherActiveRecordModelTransition
+          end
+        end
+      end
+
+      describe ".in_state" do
+        subject(:query) { MyActiveRecordModel.in_state(:succeeded) }
+
+        specify { expect { query }.to_not raise_error }
+      end
+    end
+
     context "after_commit transactional integrity" do
       before do
         MyStateMachine.class_eval do

data/spec/statesman/adapters/active_record_spec.rb

@@ -130,6 +130,31 @@ describe Statesman::Adapters::ActiveRecord, active_record: true do
         expect { adapter.create(:y, :z) }.
           to raise_exception(Statesman::TransitionConflictError)
       end
+
+      it "does not pollute the state when the transition fails" do
+        # this increments the sort_key in the database
+        adapter.create(:x, :y)
+
+        # we then pre-load the transitions for efficiency
+        preloaded_model = MyActiveRecordModel.
+          includes(:my_active_record_model_transitions).
+          find(model.id)
+
+        adapter2 = described_class.
+          new(MyActiveRecordModelTransition, preloaded_model, observer)
+
+        # Now we generate a race
+        adapter.create(:y, :z)
+        expect { adapter2.create(:y, :a) }.
+          to raise_error(Statesman::TransitionConflictError)
+
+        # The preloaded adapter should discard the preloaded info
+        expect(adapter2.last).to have_attributes(to_state: "z")
+        expect(adapter2.history).to contain_exactly(
+          have_attributes(to_state: "y"),
+          have_attributes(to_state: "z"),
+        )
+      end
     end
 
     context "when other exceptions occur" do
@@ -355,6 +380,19 @@ describe Statesman::Adapters::ActiveRecord, active_record: true do
     end
   end
 
+  it "resets last with #reload" do
+    model.save!
+    ActiveRecord::Base.transaction do
+      model.state_machine.transition_to!(:succeeded)
+      # force to cache value in last_transition instance variable
+      expect(model.state_machine.current_state).to eq("succeeded")
+      raise ActiveRecord::Rollback
+    end
+    expect(model.state_machine.current_state).to eq("succeeded")
+    model.reload
+    expect(model.state_machine.current_state).to eq("initial")
+  end
+
   context "with a namespaced model" do
     before do
       CreateNamespacedARModelMigration.migrate(:up)

data/spec/statesman/machine_spec.rb

@@ -537,6 +537,34 @@ describe Statesman::Machine do
     end
   end
 
+  describe "#last_transition_to" do
+    subject { instance.last_transition_to(:y) }
+
+    before do
+      machine.class_eval do
+        state :x, initial: true
+        state :y
+        state :z
+        transition from: :x, to: :y
+        transition from: :y, to: :z
+        transition from: :z, to: :y
+      end
+
+      instance.transition_to!(:y)
+      instance.transition_to!(:z)
+    end
+
+    let(:instance) { machine.new(my_model) }
+
+    it { is_expected.to have_attributes(to_state: "y") }
+
+    context "when there are 2 transitions to the state" do
+      before { instance.transition_to!(:y) }
+
+      it { is_expected.to eq(instance.last_transition) }
+    end
+  end
+
   describe "#can_transition_to?" do
     subject(:can_transition_to?) { instance.can_transition_to?(new_state, metadata) }
 

data/spec/support/active_record.rb

@@ -33,6 +33,11 @@ class MyActiveRecordModel < ActiveRecord::Base
   def metadata
     super || {}
   end
+
+  def reload(*)
+    state_machine.reset
+    super
+  end
 end
 
 class MyActiveRecordModelTransition < ActiveRecord::Base

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: statesman
 version: !ruby/object:Gem::Version
-  version: 7.4.0
+  version: 8.0.3
 platform: ruby
 authors:
 - GoCardless
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-08-26 00:00:00.000000000 Z
+date: 2021-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ammeter
@@ -303,7 +303,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.1
+rubygems_version: 3.1.2
 signing_key:
 specification_version: 4
 summary: A statesman-like state machine library