state_machines-audit_trail 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b8a0bfd2dd9a83185bc24c1c55d3804b2fba5a8e
+  data.tar.gz: 03e55491819582dbf56a32b494756564d0da7ffd
+SHA512:
+  metadata.gz: d1c764d8ed988ecb2a766939127e76ce902241320bd53fdce5641830bb3eb52c666179dae873d23fc2f989a5fd65013722af497716a59d65e06c5d5d5a659e6b
+  data.tar.gz: 60d5d11f419b337f253141fb36a17a51dcb2852cb549e89b64a59f4c8f06ed8a30fe7785038138a7a11884212ca1cd0b52cbac094cd9133699eb3165a5dd39f4

data/.gitignore

@@ -0,0 +1,9 @@
+*.gem
+/.bundle
+Gemfile.lock
+pkg/*
+.DS_Store
+*.rbc
+/doc
+.yardoc
+.idea

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,17 @@
+language: ruby
+sudo: false
+cache: bundler
+
+script: "bundle exec rake"
+
+services: mongodb
+rvm:
+  - 2.1
+  - 2.0.0
+  - 2.2
+  - jruby
+  - rbx-2
+matrix:
+  allow_failures:
+    - rvm: rbx-2
+    - rvm: jruby

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2011 Jesse Storimer & Willem van Bergen
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,167 @@
+[![Build Status](https://travis-ci.org/state-machines/state_machines-audit_trail.svg?branch=master)](https://travis-ci.org/state-machines/state_machines-audit_trail)
+[![Code Climate](https://codeclimate.com/github/state-machines/state_machines-audit_trail.png)](https://codeclimate.com/github/state-machines/state_machines-audit_trail)
+
+# state_machines-audit_trail
+Log transitions on a [state_machines gem](https://github.com/state-machines/state_machines) to support auditing and business process analytics.
+
+
+## Description
+
+This plugin for the [state_machines gem](https://github.com/state-machines/state_machines) adds support for keeping an audit trail
+for any state machine. Having an audit trail gives you a complete history of the state changes in your model. This history allows you
+to investigate incidents or perform analytics, like: _"How long does it take on average to go from state a to state b?"_,
+or _"What percentage of cases goes from state a to b via state c?"_
+
+For more information read [Why developers should be force-fed state machines](http://www.shopify.com/technology/3383012-why-developers-should-be-force-fed-state-machines).
+
+## ORM support
+
+Note: while the state_machines gem integrates with multiple ORMs, this plugin is currently limited to the following ORM backends:
+
+*   ActiveRecord
+*   Mongoid
+
+
+It should be easy to add new backends by looking at the implementation of the current backends. Pull requests are welcome!
+
+## Installation
+First, make the gem available by adding it to your `Gemfile`, and run `bundle install`:
+
+```ruby
+
+# this gem
+gem 'state_machines-audit_trail'
+
+# required runtime dependency for your ORM; either
+gem 'state_machines-activerecord'
+
+# OR
+gem 'state_machines-mongoid'
+```
+
+## Usage
+
+For the examples below, we will assume you have a pre-existing model called `Subscription` that has a `state_machine` configured to utilize the `state` attribute.
+
+### Create/generate a model and migration that holds the audit trail specific to your target model
+A Rails generator is provided to create a model and a migration, call it with:
+
+```ruby
+rails generate state_machines:audit_trail Subscription state
+```
+
+will generate the `SubscriptionStateTransition` model and an accompanying migration.
+
+### Configure `audit_trail` in your `state_machine`:
+
+```ruby
+class Subscription < ActiveRecord::Base
+  state_machines :state, initial: :start do
+    audit_trail
+    ...
+```
+
+### That's it!
+`audit_trail` will register an `after_transition` callback that is used to log all transitions including the initial state if there is one.
+
+## Configuration options
+
+### `:initial` - turn off initial state logging
+By default, upon instantiation, a `StateTransition` is saved for `null => initial` state.  This is useful to understand the full history
+of any model, but there are cases where this can pollute the `audit_trail`.  For example, when a model has multiple `state_machine`s
+that use a single `StateTransition` model for persistence (in conjunction with `context` below), there would be multiple initial state
+transitions.  By configuring `initial: false`, it will skip the initial state transition logging for this specific `state_machine`, while
+leaving the others in the model unaffected.
+```ruby
+audit_trail initial: false
+```
+
+### `:class` - custom state transition class
+If your `Transition` model does not use the default naming scheme, provide it using the `:class` option:
+```ruby
+audit_trail class: FooStateTransition
+```
+
+An example use of a custom `:class` and `:context` (below) would be for a model that has multiple `state_machine` definitions.  The combination
+of these options would allow the use of one transition class that logged state information from both state machines.
+
+### `:context` - storing additional attribute or method values
+Using the `:context` option, you can store method results (or attributes exposed as methods) in the state transition class.
+
+In order to utilize this feature, you need to:
+
+1. add a field/column to your state transition class (i.e. `SubscriptionStateTransitions`) and perhaps underlying database through a migration
+2. expose the attribute as a method, or create a method to compute a dynamic value
+3. configure `:context`
+
+#### Example 1 - Store a single attribute value
+Store `Subscription` `field1` in `Transition` field `field1`:
+```ruby
+audit_trail :context: :field1
+```
+
+#### Example 2 - Store multiple attribute values
+Store `Subscription` `field1` and `field2` in `Transition` fields `field1` and `field2`:
+```ruby
+audit_trail context: [:field1, :field2]
+```
+
+#### Example 3 - Store simple method results
+Store simple method results.
+
+Sometimes it can be useful to store dynamically computed information, such as those from a `Subscription`  method `#plan_time_remaining`
+
+
+```ruby
+class Subscription < ActiveRecord::Base
+  state_machines :state, initial: :start do
+    audit_trail :context: :plan_time_remaining
+    ...
+
+  def plan_time_remaining
+    # Dynamically computed field e.g., based on other models
+    ...
+```
+
+#### Example 4 - Store advanced method results
+Store method results that interrogate the transition for information such as `event` arguments:
+
+```ruby
+class Subscription < ActiveRecord::Base
+  state_machines :state, initial: :start do
+    audit_trail :context: :user_name
+    ...
+
+  # method receives a state_machines transition object
+  def user_name(transition)
+    if transition.args.present?
+      user_id = transition.args.last.delete(:user_id)
+      User.find(user_id).name
+    else
+      'Undefined User'
+    end
+    ...
+
+model = Subscription.first
+model.ignite!('arg1, 'arg2', 'arg3', user_id: 1)
+```
+
+## About
+
+### Maintainers
+Conversion from the original code to `state_machines` by [AlienFast](http://alienfast.com).
+
+### Original Authors
+[The original plugin](https://github.com/wvanbergen/state_machine-audit_trail) was written by Jesse Storimer and Willem van Bergen for Shopify.
+Mongoid support was contributed by [Siddharth](https://github.com/svs).
+
+### License
+Released under the MIT license (see LICENSE).
+
+## Contributing
+
+1. Fork it ( https://github.com/state-machines/state_machines-audit_trail/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,9 @@
+require 'bundler/gem_tasks'
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.pattern = "./spec/**/*_spec.rb"
+  task.rspec_opts = ['--color']
+end
+
+task :default => [:spec]

data/lib/state_machines-audit_trail.rb

@@ -0,0 +1,2 @@
+# To keep Rails happy
+require 'state_machines/audit_trail'

data/lib/state_machines/audit_trail.rb

@@ -0,0 +1,16 @@
+require 'state_machines'
+
+module StateMachines
+  module AuditTrail
+    def self.setup
+      StateMachines::Machine.send(:include, StateMachines::AuditTrail::TransitionAuditing)
+    end
+  end
+end
+
+require 'state_machines/audit_trail/version'
+require 'state_machines/audit_trail/transition_auditing'
+require 'state_machines/audit_trail/backend'
+require 'state_machines/audit_trail/railtie' if defined?(::Rails)
+
+StateMachines::AuditTrail.setup

data/lib/state_machines/audit_trail/backend.rb

@@ -0,0 +1,56 @@
+class StateMachines::AuditTrail::Backend < Struct.new(:transition_class, :owner_class, :context)
+
+  autoload :Mongoid, 'state_machines/audit_trail/backend/mongoid'
+  autoload :ActiveRecord, 'state_machines/audit_trail/backend/active_record'
+
+  #
+  # Resolve field values and #persist
+  #   - object: the object being watched by the state_machines observer
+  #   - transition: state machine transition object that state machine passes to after/before transition callbacks
+  #
+  def log(object, transition)
+    fields = {event: transition.event ? transition.event.to_s : nil, from: transition.from, to: transition.to}
+    [context].flatten(1).each { |field|
+      fields[field] = resolve_context(object, field, transition)
+    } unless self.context.nil?
+
+    # begin
+    persist(object, fields)
+    # rescue => e
+    #   puts "\nUncaught #{e.class} persisting audit_trail: #{e.message}"
+    #   puts "\t" + e.backtrace.join($/ + "\t")
+    #   raise e
+    # end
+  end
+
+  #
+  # Creates an instance of the Backend class which does the actual persistence of transition state information.
+  #   - transition_class: the Class which holds the audit trail
+  #
+  # To add a new ORM, implement something similar to lib/state_machines/audit_trail/backend/active_record.rb
+  # and return from here the appropriate object based on which ORM the transition_class is using
+  #
+  def self.create_for(transition_class, owner_class, context = nil)
+    if Object.const_defined?('ActiveRecord') && transition_class.ancestors.include?(::ActiveRecord::Base)
+      return StateMachines::AuditTrail::Backend::ActiveRecord.new(transition_class, owner_class, context)
+    elsif Object.const_defined?('Mongoid') && transition_class.ancestors.include?(::Mongoid::Document)
+      return StateMachines::AuditTrail::Backend::Mongoid.new(transition_class, owner_class, context)
+    else
+      raise 'Not implemented. Only support for ActiveRecord and Mongoid is implemented. Pull requests welcome.'
+    end
+  end
+
+  protected
+
+  def persist(object, fields)
+    raise 'Not implemented. Implement in a subclass.'
+  end
+
+  def resolve_context(object, context, transition)
+    if object.method(context).arity != 0
+      object.send(context, transition)
+    else
+      object.send(context)
+    end
+  end
+end

data/lib/state_machines/audit_trail/backend/active_record.rb

@@ -0,0 +1,23 @@
+require 'state_machines-activerecord'
+
+class StateMachines::AuditTrail::Backend::ActiveRecord < StateMachines::AuditTrail::Backend
+  attr_accessor :context
+
+  def initialize(transition_class, owner_class, context = nil)
+    @association = transition_class.to_s.tableize.split('/').last.to_sym
+    super transition_class, owner_class
+    self.context = context # FIXME: actually not sure why we need to do this, but tests fail otherwise. Something with super's Struct?
+    owner_class.has_many(@association, class_name: transition_class.to_s) unless owner_class.reflect_on_association(@association)
+  end
+
+  def persist(object, fields)
+    # Let ActiveRecord manage the timestamp for us so it does the right thing with regards to timezones.
+    if object.new_record?
+      object.send(@association).build(fields)
+    else
+      object.send(@association).create(fields)
+    end
+
+    nil
+  end
+end

data/lib/state_machines/audit_trail/backend/mongoid.rb

@@ -0,0 +1,13 @@
+require 'state_machines-mongoid'
+
+#
+# Populate and persist the state transition to Mongoid
+#
+class StateMachines::AuditTrail::Backend::Mongoid < StateMachines::AuditTrail::Backend
+
+  def persist(object, fields)
+    foreign_key_field = transition_class.relations.keys.first
+    fields = fields.merge({foreign_key_field => object, created_at: Time.now})
+    transition_class.create(fields)
+  end
+end

data/lib/state_machines/audit_trail/railtie.rb

@@ -0,0 +1,5 @@
+class StateMachines::AuditTrail::Railtie < ::Rails::Railtie
+  generators do
+    require 'state_machines/audit_trail_generator'
+  end
+end

data/lib/state_machines/audit_trail/transition_auditing.rb

@@ -0,0 +1,59 @@
+require 'ostruct'
+#
+# This module inserts hooks into the state machine.
+# The transition_class is the class (optionally specified with the :class option) for the model which
+# records audit information from one single transition i.e. SubscriptionStateTransition.
+#
+# Multiple `SubscriptionStateTransition`s compose the 'audit_trail'.
+#
+module StateMachines::AuditTrail::TransitionAuditing
+
+  # Hook for audit_trail inside a a state_machine declaration.
+  #
+  # options:
+  #   - :class - custom state transition class
+  #   - :context - methods to call/store in field of same name in the state transition class
+  #   - :initial - if false, won't log null => initial state transition upon instantiation
+  #
+  def audit_trail(options = {})
+    state_machine = self
+    if options[:class].presence
+      raise ":class option[#{options[:class]}] must be a class (not a string)." unless options[:class].is_a? Class
+    end
+    transition_class = options[:class] || default_transition_class
+
+    # backend implements #log to store transition information
+    @backend = StateMachines::AuditTrail::Backend.create_for(transition_class, self.owner_class, options[:context])
+
+    # Initial state logging can be turned off. Very useful for a model with multiple state_machines using a single TransitionState object for logging
+    unless options[:initial] == false
+      unless state_machine.action == nil
+        # Log the initial transition from null => initial (upon object instantiation)
+        state_machine.owner_class.after_initialize do |object|
+          current_state = object.send(state_machine.attribute)
+          if !current_state.nil?
+            state_machine.backend.log(object, OpenStruct.new(to: current_state))
+          end
+        end
+      end
+    end
+
+    # Log any transition (other than initial)
+    state_machine.after_transition do |object, transition|
+      state_machine.backend.log(object, transition)
+    end
+  end
+
+  # Public returns an instance of the class which does the actual audit trail logging
+  def backend
+    @backend
+  end
+
+  private
+
+  def default_transition_class
+    owner_class_or_base_class = owner_class.respond_to?(:base_class) ? owner_class.base_class : owner_class
+    name = "#{owner_class_or_base_class.name}#{attribute.to_s.camelize}Transition"
+    name.constantize
+  end
+end

data/lib/state_machines/audit_trail/version.rb

@@ -0,0 +1,5 @@
+module StateMachines
+  module AuditTrail
+    VERSION = '1.0.0'
+  end
+end

data/lib/state_machines/audit_trail_generator.rb

@@ -0,0 +1,29 @@
+require 'rails/generators'
+
+class StateMachines::AuditTrailGenerator < ::Rails::Generators::Base
+
+  source_root File.join(File.dirname(__FILE__), 'templates')
+
+  argument :source_model
+  argument :state_attribute, default: 'state'
+  argument :transition_model, default: ''
+
+
+  def create_model
+    args = [transition_class_name,
+            "#{source_model.demodulize.tableize.singularize}:references",
+            'event:string',
+            'from:string',
+            'to:string',
+            'created_at:timestamp',
+            '--no-timestamps',
+            '--no-fixtures']
+    generate 'model', args.join(' ')
+  end
+
+  protected
+
+  def transition_class_name
+    transition_model.blank? ? "#{source_model.camelize}#{state_attribute.camelize}Transition" : transition_model
+  end
+end