statesman 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 854b8cc89e069fa3322067960b77dd3cf82364bc
-  data.tar.gz: 8b9dd4292751c9323ebcf59b4ee9373ef9ed42eb
+  metadata.gz: b7adec92ffe517ecf4227b1190dcf1289abce8fe
+  data.tar.gz: 2f5876f6d294df4f2d52272c473d5c4521884d1d
 SHA512:
-  metadata.gz: 6df28629b85027c1a3d3ae6e04e676d6037f500ad9448a5f50afaf2ad21d3d7159537acbeb33786f99293ced225ed487fcfa897068adff2a10447df31ad333bc
-  data.tar.gz: 5300f0546e4929cb29b5ab4d86af48a1e9232a443e179c9cec180ee82109e481e34a317e43b3fe5f077bbd1320d3b027e8976bdcdf89dea36d7b8f11fc02d0fa
+  metadata.gz: 9e9be2c9b771cbd4f2d19b7de27854f047659c33deb6907af3b38bb8130feda521f9faf22ffe7560dc01fed63390ab569aae6b8fe3469e1d4159efba430ba428
+  data.tar.gz: e4e509269a3fd7adcfc3cfa15be27cef5d5e36e8e04fea8acf3c1fb6cef213ed3d91174c0efee5985eb691ec15ab59d105579769e651b4e1ca1d6546eb2cdc99

data/.rubocop.yml

@@ -4,8 +4,11 @@ AllCops:
   Include:
     - Rakefile
     - statesman.gemfile
+    - lib/tasks/*.rake
   Exclude:
-    - vendor/**
+    - vendor/**/*
+    - .*/**
+    - spec/fixtures/**/*
 
 StringLiterals:
   Enabled: false
@@ -36,3 +39,6 @@ GuardClause:
 
 SingleSpaceBeforeFirstArg:
   Enabled: false
+
+Style/DotPosition:
+  EnforcedStyle: 'trailing'

data/.travis.yml

@@ -1,11 +1,26 @@
+language: ruby
+
 rvm:
   - 2.1
   - 2.0.0
   - 1.9.3
+
+sudo: false
+
 services: mongodb
+
+before_script:
+  - mysql -e 'CREATE DATABASE statesman_test;'
+  - psql -c 'CREATE DATABASE statesman_test;' -U postgres
+
 script:
- - bundle exec rubocop
- - bundle exec rake
+  - bundle exec rubocop
+  - bundle exec rake
+
 env:
-  - "RAILS_VERSION=4.1.7"
-  - "RAILS_VERSION=4.2.0.rc2"
+  - "RAILS_VERSION=3.2.21"
+  - "RAILS_VERSION=4.0.12"
+  - "RAILS_VERSION=4.1.8"
+  - "RAILS_VERSION=4.2.0"
+  - "RAILS_VERSION=4.2.0 DATABASE_URL=mysql2://root@localhost/statesman_test"
+  - "RAILS_VERSION=4.2.0 DATABASE_URL=postgres://postgres@localhost/statesman_test"

data/CHANGELOG.md

@@ -1,3 +1,33 @@
+## v1.2.0 18 March 2015
+
+*Changes*
+
+- Add a `most_recent` column to transition tables to greatly speed up queries (ActiveRecord adapter only).
+  - All queries are backwards-compatible, so everything still works without the new column.
+  - The upgrade path is:
+    - Generate and run a migration for adding the column, by running `rails generate statesman:add_most_recent <ParentModel> <TransitionModel>`.
+    - Backfill the `most_recent` column on old records by running `rake statesman:backfill_most_recent[ParentModel] `.
+    - Add constraints and indexes to the transition table that make use of the new field, by running `rails g statesman:add_constraints_to_most_recent <ParentModel> <TransitionModel>`.
+  - The upgrade path has been designed to be zero-downtime, even on large tables. As a result, please note that queries will only use the `most_recent` field after the constraints have been added.
+- `ActiveRecordQueries.{not_,}in_state` now accepts an array of states.
+
+
+## v1.1.0 9 December 2014
+*Fixes*
+
+- Support for Rails 4.2.0.rc2:
+  - Remove use of serialized_attributes when using 4.2+. (patch by [@greysteil](https://github.com/greysteil))
+  - Use reflect_on_association rather than directly using the reflections hash. (patch by [@timrogers](https://github.com/timrogers))
+- Fix `ActiveRecordQueries.in_state` when `Model.initial_state` is defined as a symbol. (patch by [@isaacseymour](https://github.com/isaacseymour))
+
+*Changes*
+
+- Transition metadata now defaults to `{}` rather than `nil`. (patch by [@greysteil](https://github.com/greysteil))
+
+## v1.0.0 21 November 2014
+
+No changes from v1.0.0.beta2
+
 ## v1.0.0.beta2 10 October 2014
 *Breaking changes*
 

data/README.md

@@ -60,7 +60,7 @@ class Order < ActiveRecord::Base
   has_many :order_transitions
 
   def state_machine
-    OrderStateMachine.new(self, transition_class: OrderTransition)
+    @state_machine ||= OrderStateMachine.new(self, transition_class: OrderTransition)
   end
 
   private
@@ -222,6 +222,13 @@ It is also possible to use the PostgreSQL JSON column if you are using Rails 4.
 * Remove `include Statesman::Adapters::ActiveRecordTransition` statement from your
   transition model
 
+#### Creating transitions without using `#transition_to` with ActiveRecord
+
+By default, Statesman will include a `most_recent` column on the transitions
+table, and update its value each time `#transition_to` is called. If you create
+transitions manually (for example to backfill for a new state) you will need to
+set the `most_recent` attribute manually.
+
 
 ## Configuration
 
@@ -289,6 +296,9 @@ model object and transition object are passed as arguments to the callback.
 This callback can have side-effects as it will only be run once immediately
 after the transition.
 
+If you specify `after_commit: true`, the callback will be executed once the
+transition has been committed to the database.
+
 #### `Machine.new`
 ```ruby
 my_machine = Machine.new(my_model, transition_class: MyTransitionModel)
@@ -423,40 +433,6 @@ describe "some callback" do
 end
 ```
 
-#### Creating models in certain states
-
-Sometimes you'll want to test a guard/transition from one state to another, where the state you want to go from is not the initial state of the model. In this instance you'll need to construct a model instance in the state required. However, if you have strict guards, this can be a pain. One way to get around this in tests is to directly create the transitions in the database, hence avoiding the guards.
-
-We use [FactoryGirl](https://github.com/thoughtbot/factory_girl) for creating our test objects. Given an `Order` model that is backed by Statesman, we can easily set it up to be in a particular state:
-
-```ruby
-factory :order do
-  property "value"
-  ...
-
-  trait :shipped do
-    after(:create) do |order|
-      FactoryGirl.create(:order_transition, :shipped, order: order)
-    end
-  end
-end
-
-factory :order_transition do
-  order
-  ...
-
-  trait :shipped do
-    to_state "shipped"
-  end
-end
-```
-
-This means you can easily create an `Order` in the `shipped` state:
-
-```ruby
-let(:shipped_order) { FactoryGirl.create(:order, :shipped) }
-```
-
 ---
 
 GoCardless ♥ open source. If you do too, come [join us](https://gocardless.com/jobs#software-engineer).

data/lib/generators/statesman/add_constraints_to_most_recent_generator.rb

@@ -0,0 +1,28 @@
+require "rails/generators"
+require "generators/statesman/generator_helpers"
+
+module Statesman
+  class AddConstraintsToMostRecentGenerator < Rails::Generators::Base
+    include Statesman::GeneratorHelpers
+
+    desc "Adds uniqueness and not-null constraints to the most recent column " \
+         "for a statesman transition"
+
+    argument :parent, type: :string, desc: "Your parent model name"
+    argument :klass,  type: :string, desc: "Your transition model name"
+
+    source_root File.expand_path('../templates', __FILE__)
+
+    def create_model_file
+      template("add_constraints_to_most_recent_migration.rb.erb",
+               migration_file_name)
+    end
+
+    private
+
+    def migration_file_name
+      "db/migrate/#{next_migration_number}_"\
+      "add_constraints_to_most_recent_for_#{table_name}.rb"
+    end
+  end
+end

data/lib/generators/statesman/add_most_recent_generator.rb

@@ -0,0 +1,25 @@
+require "rails/generators"
+require "generators/statesman/generator_helpers"
+
+module Statesman
+  class AddMostRecentGenerator < Rails::Generators::Base
+    include Statesman::GeneratorHelpers
+
+    desc "Adds most_recent to a statesman transition model"
+
+    argument :parent, type: :string, desc: "Your parent model name"
+    argument :klass,  type: :string, desc: "Your transition model name"
+
+    source_root File.expand_path('../templates', __FILE__)
+
+    def create_model_file
+      template("add_most_recent_migration.rb.erb", migration_file_name)
+    end
+
+    private
+
+    def migration_file_name
+      "db/migrate/#{next_migration_number}_add_most_recent_to_#{table_name}.rb"
+    end
+  end
+end

data/lib/generators/statesman/generator_helpers.rb

@@ -28,9 +28,13 @@ module Statesman
       klass.demodulize.underscore.pluralize
     end
 
+    def index_name(index_id)
+      "index_#{table_name}_#{index_id}"
+    end
+
     def mysql?
-      ActiveRecord::Base.configurations[Rails.env]
-        .try(:[], "adapter").try(:match, /mysql/)
+      ActiveRecord::Base.configurations[Rails.env].
+        try(:[], "adapter").try(:match, /mysql/)
     end
   end
 end

data/lib/generators/statesman/templates/add_constraints_to_most_recent_migration.rb.erb

@@ -0,0 +1,13 @@
+class AddConstraintsToMostRecentFor<%= migration_class_name %> < ActiveRecord::Migration
+  disable_ddl_transaction!
+
+  def up
+    add_index :<%= table_name %>, [:<%= parent_id %>, :most_recent], unique: true, where: "most_recent", name: "index_<%= table_name %>_parent_most_recent", algorithm: :concurrently
+    change_column_null :<%= table_name %>, :most_recent, false
+  end
+
+  def down
+    remove_index :<%= table_name %>, name: "index_<%= table_name %>_parent_most_recent"
+    change_column_null :<%= table_name %>, :most_recent, true
+  end
+end

data/lib/generators/statesman/templates/add_most_recent_migration.rb.erb

@@ -0,0 +1,9 @@
+class AddMostRecentTo<%= migration_class_name %> < ActiveRecord::Migration
+  def up
+    add_column :<%= table_name %>, :most_recent, :boolean, null: true
+  end
+
+  def down
+    remove_column :<%= table_name %>, :most_recent
+  end
+end

data/lib/generators/statesman/templates/create_migration.rb.erb

@@ -5,10 +5,11 @@ class Create<%= migration_class_name %> < ActiveRecord::Migration
       t.text :metadata<%= ", default: \"{}\"" unless mysql? %>
       t.integer :sort_key, null: false
       t.integer :<%= parent_id %>, null: false
-      t.timestamps
+      t.boolean :most_recent, null: false
+      t.timestamps null: false
     end
 
-    add_index :<%= table_name %>, :<%= parent_id %>
-    add_index :<%= table_name %>, [:sort_key, :<%= parent_id %>], unique: true
+    add_index :<%= table_name %>, [:<%= parent_id %>, :sort_key], unique: true, name: "<%= index_name :parent_sort %>"
+    add_index :<%= table_name %>, [:<%= parent_id %>, :most_recent], unique: true, where: "most_recent", name: "<%= index_name :parent_most_recent %>"
   end
 end

data/lib/generators/statesman/templates/update_migration.rb.erb

@@ -4,10 +4,11 @@ class AddStatesmanTo<%= migration_class_name %> < ActiveRecord::Migration
     add_column :<%= table_name %>, :metadata, :text<%= ", default: \"{}\"" unless mysql? %>
     add_column :<%= table_name %>, :sort_key, :integer, null: false
     add_column :<%= table_name %>, :<%= parent_id %>, :integer, null: false
-    add_column :<%= table_name %>, :created_at, :datetime
-    add_column :<%= table_name %>, :updated_at, :datetime
+    add_column :<%= table_name %>, :most_recent, null: false
+    add_column :<%= table_name %>, :created_at, :datetime, null: false
+    add_column :<%= table_name %>, :updated_at, :datetime, null: false
 
-    add_index :<%= table_name %>, :<%= parent_id %>
-    add_index :<%= table_name %>, [:sort_key, :<%= parent_id %>], unique: true
+    add_index :<%= table_name %>, [:<%= parent_id %>, :sort_key], unique: true, name: "<%= index_name :parent_sort  %>"
+    add_index :<%= table_name %>, [:<%= parent_id %>, :most_recent], unique: true, where: "most_recent", name: "<%= index_name :parent_most_recent %>"
   end
 end

data/lib/statesman.rb

@@ -15,6 +15,7 @@ module Statesman
     autoload :MongoidTransition,
              "statesman/adapters/mongoid_transition"
   end
+  require 'statesman/railtie' if defined?(::Rails::Railtie)
 
   # Example:
   #   Statesman.configure do

data/lib/statesman/adapters/active_record.rb

@@ -27,8 +27,8 @@ module Statesman
         to = to.to_s
         create_transition(from, to, metadata)
       rescue ::ActiveRecord::RecordNotUnique => e
-        if e.message.include?('sort_key') &&
-           e.message.include?(@transition_class.table_name)
+        if e.message.include?(@transition_class.table_name) &&
+           e.message.include?('sort_key') || e.message.include?('most_recent')
           raise TransitionConflictError, e.message
         else raise
         end
@@ -53,11 +53,16 @@ module Statesman
       private
 
       def create_transition(from, to, metadata)
-        transition = transitions_for_parent.build(to_state: to,
-                                                  sort_key: next_sort_key,
-                                                  metadata: metadata)
+        transition_attributes = { to_state: to,
+                                  sort_key: next_sort_key,
+                                  metadata: metadata }
+
+        transition_attributes.merge!(most_recent: true) if most_recent_column?
+
+        transition = transitions_for_parent.build(transition_attributes)
 
         ::ActiveRecord::Base.transaction do
+          unset_old_most_recent
           @observer.execute(:before, from, to, transition)
           transition.save!
           @last_transition = transition
@@ -72,14 +77,24 @@ module Statesman
         @parent_model.send(@transition_class.table_name)
       end
 
+      def unset_old_most_recent
+        return unless most_recent_column?
+        transitions_for_parent.update_all(most_recent: false)
+      end
+
+      def most_recent_column?
+        transition_class.columns_hash.include?("most_recent")
+      end
+
       def next_sort_key
         (last && last.sort_key + 10) || 0
       end
 
       def serialized?(transition_class)
-        if ::ActiveRecord.gem_version >= Gem::Version.new('4.2.0.a')
-          transition_class.columns_hash["metadata"]
-            .cast_type.is_a?(::ActiveRecord::Type::Serialized)
+        if ::ActiveRecord.respond_to?(:gem_version) &&
+           ::ActiveRecord.gem_version >= Gem::Version.new('4.2.0.a')
+          transition_class.columns_hash["metadata"].
+            cast_type.is_a?(::ActiveRecord::Type::Serialized)
         else
           transition_class.serialized_attributes.include?("metadata")
         end

data/lib/statesman/adapters/active_record_queries.rb

@@ -7,25 +7,51 @@ module Statesman
 
       module ClassMethods
         def in_state(*states)
-          states = states.map(&:to_s)
+          states = states.flatten.map(&:to_s)
 
-          joins(transition1_join)
-            .joins(transition2_join)
-            .where(state_inclusion_where(states), states)
-            .where("transition2.id" => nil)
+          if use_most_recent_column?
+            in_state_with_most_recent(states)
+          else
+            in_state_without_most_recent(states)
+          end
         end
 
         def not_in_state(*states)
-          states = states.map(&:to_s)
+          states = states.flatten.map(&:to_s)
 
-          joins(transition1_join)
-            .joins(transition2_join)
-            .where("NOT (#{state_inclusion_where(states)})", states)
-            .where("transition2.id" => nil)
+          if use_most_recent_column?
+            not_in_state_with_most_recent(states)
+          else
+            not_in_state_without_most_recent(states)
+          end
         end
 
         private
 
+        def in_state_with_most_recent(states)
+          joins(most_recent_transition_join).
+            where(states_where('last_transition', states), states)
+        end
+
+        def not_in_state_with_most_recent(states)
+          joins(most_recent_transition_join).
+            where("NOT (#{states_where('last_transition', states)})", states)
+        end
+
+        def in_state_without_most_recent(states)
+          joins(transition1_join).
+            joins(transition2_join).
+            where(states_where('transition1', states), states).
+            where("transition2.id" => nil)
+        end
+
+        def not_in_state_without_most_recent(states)
+          joins(transition1_join).
+            joins(transition2_join).
+            where("NOT (#{states_where('transition1', states)})", states).
+            where("transition2.id" => nil)
+        end
+
         def transition_class
           raise NotImplementedError, "A transition_class method should be " \
                                      "defined on the model"
@@ -55,15 +81,36 @@ module Statesman
              AND transition2.sort_key > transition1.sort_key"
         end
 
-        def state_inclusion_where(states)
+        def most_recent_transition_join
+          "LEFT OUTER JOIN #{transition_name} AS last_transition
+             ON #{table_name}.id = last_transition.#{model_foreign_key}
+             AND last_transition.most_recent = #{db_true}"
+        end
+
+        def states_where(temporary_table_name, states)
           if initial_state.to_s.in?(states.map(&:to_s))
-            'transition1.to_state IN (?) OR ' \
-            'transition1.to_state IS NULL'
+            "#{temporary_table_name}.to_state IN (?) OR " \
+            "#{temporary_table_name}.to_state IS NULL"
           else
-            'transition1.to_state IN (?) AND ' \
-            'transition1.to_state IS NOT NULL'
+            "#{temporary_table_name}.to_state IN (?) AND " \
+            "#{temporary_table_name}.to_state IS NOT NULL"
           end
         end
+
+        def db_true
+          ::ActiveRecord::Base.connection.quote(true)
+        end
+
+        # Only use the most_recent column if it has a unique index guaranteeing
+        # it has good data
+        def use_most_recent_column?
+          ::ActiveRecord::Base.connection.index_exists?(
+            transition_name,
+            [model_foreign_key, :most_recent],
+            unique: true,
+            name: "index_#{transition_name}_parent_most_recent"
+          )
+        end
       end
     end
   end