historiographer 1.0.0

data/lib/historiographer/history.rb

@@ -0,0 +1,175 @@
+require 'active_support/concern'
+
+#
+# See Historiographer for more details
+#
+# Historiographer::History is a mixin that is
+# automatically included in any History class (e.g. RetailerProductHistory).
+#
+# A History record represents a snapshot of a primary record at a particular point
+# in time.
+#
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+#
+# E.g. You have a RetailerProduct (ID: 1) that makes the following changes:
+#
+# 1) rp = RetailerProduct.create(name: "Sabra")
+#
+# 2) rp.update(name: "Sabra Hummus")
+#
+# 3) rp.update(name: "Sabra Pine Nut Hummus")
+#
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+#
+# Your RetailerProduct record looks like this:
+#
+# <#RetailerProduct:0x007fbf00c78f00 name: "Sabra Pine Nut Hummus">
+#
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+#
+# But your RetailerProductHistories look like this:
+#
+# rp.histories
+#
+# <#RetailerProductHistory:0x007fbf00c78f01 name: "Sabra", history_started_at: 1.minute.ago, history_ended_at: 30.seconds.ago>
+# <#RetailerProductHistory:0x007fbf00c78f02 name: "Sabra Hummus", history_started_at: 30.seconds.ago, history_ended_at: 10.seconds.ago>
+# <#RetailerProductHistory:0x007fbf00c78f03 name: "Sabra Pine Nut Hummus", history_started_at: 10.seconds.ago, history_ended_at: nil>
+#
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+#
+# Since these Histories are intended to represent a snapshot in time, they should never be
+# deleted or modified directly. Historiographer will manage all of the nuances for you.
+#
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+#
+# Your classes should be written like this:
+#
+# class RetailerProduct < ActiveRecord::Base
+#   include Historiographer
+# end
+#
+# # This class is created automatically. You don't
+# # need to create a file yourself, unless you
+# # want to add additional methods.
+# #
+# class RetailerProductHistory < ActiveRecord::Base
+#   include Historiographer::History
+# end
+#
+module Historiographer
+  module History
+    extend ActiveSupport::Concern
+
+    included do |base|
+
+      #
+      # A History class (e.g. RetailerProductHistory) will gain
+      # access to a current scope, returning
+      # the most recent history.
+      #
+      # Although we never want there to be more than 1 current history,
+      # in the off chance this invariant is broken, this method is
+      # guaranteed to only return an array containing the most recent history.
+      #
+      scope :current, -> { where(history_ended_at: nil).order(id: :desc).limit(1) }
+
+      #
+      # A History class will be linked to the user
+      # that made the changes.
+      #
+      # E.g.
+      #
+      # RetailerProductHistory.first.user
+      #
+      # To use histories, a user class must be defined.
+      #
+      belongs_to :user, foreign_key: :history_user_id
+
+      # 
+      # Historiographer is opinionated about how History classes
+      # should be named.
+      #
+      # For a class named "RetailerProductHistory", the History class should be named
+      # "RetailerProductHistory."
+      #
+      foreign_class_name = base.name.gsub(/History$/) {}        # e.g. "RetailerProductHistory" => "RetailerProduct"
+      association_name   = foreign_class_name.underscore.to_sym # e.g. "RetailerProduct"        => :retailer_product
+
+      #
+      # Historiographer will automatically setup the association
+      # to the primary class (e.g. RetailerProduct)
+      #
+      # If the History class has already defined this association, raise
+      # an error, because we don't yet see any reason why end users
+      # should be allowed to override this method.
+      #
+      # At some point, we may decide to allow this, but for now, we don't
+      # know what the requirements/use cases would be.
+      #
+      # e.g.
+      #
+      # if RetailerProductHistory.respond_to?(:retailer_product)
+      #   raise "RetailerProductHistory already has #retailer_product association. Talk to Brett if this is a legit use case"
+      # else
+      #   belongs_to :retailer_product, class_name: RetailerProduct
+      # end
+      #
+      if base.respond_to?(association_name)
+        raise "#{base} already has ##{association_name} association. Talk to Brett if this is a legit use case."
+      else
+        belongs_to association_name, class_name: foreign_class_name
+      end
+
+      #
+      # A History record should never be destroyed.
+      #
+      # History records are immutable, so we enforce
+      # this constraint as much as we can at the Rails layer.
+      #
+      def destroy
+        false
+      end
+
+      def destroy!
+        false
+      end
+
+      #
+      # History records should never be updated, except to set
+      # history_ended_at (when they are overridden by future histories).
+      #
+      # If the record was already persisted, then they only change it
+      # is allowed to make is to history_ended_at.
+      #
+      # If the record was not already persisted, proceed as normal.
+      #
+      def save(*args)
+        if persisted? && (changes.keys - %w(history_ended_at)).any?
+          false
+        else
+          super
+        end
+      end
+
+      def save!(*args)
+        if persisted? && (changes.keys - %w(history_ended_at)).any?
+          false
+        else
+          super
+        end
+      end
+    end
+
+    class_methods do
+
+      #
+      # The foreign key to the primary class.
+      #
+      # E.g. PostHistory.history_foreign_key => post_id
+      #
+      def history_foreign_key
+        name.gsub(/History$/) {}.foreign_key
+      end
+    end
+  end
+end

data/lib/historiographer/history_migration.rb

@@ -0,0 +1,78 @@
+module Historiographer
+  module HistoryMigration
+    #
+    # class CreateAdGroupHistories < ActiveRecord::Migration
+    #  def change
+    #    create_table :ad_group_histories do |t|
+    #      t.histories
+    #    end
+    #  end
+    # end
+    #
+    # t.histories(except: ["name"]) # don't include name column
+    # t.histories(only: ["name"])   # only include name column
+    # t.histories(no_business_columns: true) # only add history timestamps and history_user_id; manually add your own columns
+    #
+    # Will automatically add user_id, history_started_at,
+    # and history_ended_at columns
+    #
+    def histories(except: [], only: [], no_business_columns: false)
+      original_table_name = self.name.gsub(/_histories$/) {}.pluralize
+      foreign_key         = original_table_name.singularize.foreign_key
+
+      class_definer = Class.new(ActiveRecord::Base) do
+      end
+
+      class_name = original_table_name.classify
+      klass      = Object.const_set(class_name, class_definer)
+      original_columns = klass.columns.reject { |c| c.name == "id" || except.include?(c.name) || (only.any? && only.exclude?(c.name)) || no_business_columns }
+
+      integer foreign_key.to_sym, null: false
+
+      original_columns.each do |column|
+        opts = {}
+        opts.merge!(column.as_json.clone)
+        # opts.merge!(column.type.as_json.clone)
+
+        send(column.type, column.name, opts.symbolize_keys!)
+      end
+
+      datetime :history_started_at, null: false
+      datetime :history_ended_at
+      integer :history_user_id
+
+      index :history_started_at
+      index :history_ended_at
+      index :history_user_id
+      index foreign_key
+
+      indices_sql = <<-SQL
+        SELECT
+            a.attname AS column_name
+        FROM
+            pg_class t,
+            pg_class i,
+            pg_index ix,
+            pg_attribute a
+        WHERE
+            t.oid = ix.indrelid
+            AND i.oid = ix.indexrelid
+            AND a.attrelid = t.oid
+            AND a.attnum = ANY(ix.indkey)
+            AND t.relkind = 'r'
+            AND t.relname = ?
+        ORDER BY
+            t.relname,
+            i.relname;
+      SQL
+
+      indices_query_array = [indices_sql, original_table_name]
+      indices_sanitized_query = klass.send(:sanitize_sql_array, indices_query_array)
+
+      klass.connection.execute(indices_sanitized_query).to_a.map(&:values).flatten.reject { |i| i == "id" }.each do |index_name|
+        index index_name.to_sym
+      end
+
+    end
+  end
+end

data/lib/historiographer/history_migration_mysql.rb

@@ -0,0 +1,54 @@
+module Historiographer
+  module HistoryMigrationMysql
+    #
+    # class CreateAdGroupHistories < ActiveRecord::Migration
+    #  def change
+    #    create_table :ad_group_histories do |t|
+    #      t.histories
+    #    end
+    #  end
+    # end
+    #
+    # t.histories(except: ["name"]) # don't include name column
+    # t.histories(only: ["name"])   # only include name column
+    # t.histories(no_business_columns: true) # only add history timestamps and history_user_id; manually add your own columns
+    #
+    # Will automatically add user_id, history_started_at,
+    # and history_ended_at columns
+    #
+    def histories(except: [], only: [], no_business_columns: false)
+      original_table_name = self.name.gsub(/_histories$/) {}.pluralize
+      foreign_key         = original_table_name.singularize.foreign_key
+
+      class_definer = Class.new(ActiveRecord::Base) do
+      end
+
+      class_name = original_table_name.classify
+      klass      = Object.const_set(class_name, class_definer)
+      original_columns = klass.columns.reject { |c| c.name == "id" || except.include?(c.name) || (only.any? && only.exclude?(c.name)) || no_business_columns }
+
+      integer foreign_key.to_sym, null: false
+
+      original_columns.each do |column|
+        opts = {}
+        opts.merge!(column.as_json.clone)
+
+        send(column.type, column.name, opts.symbolize_keys!)
+      end
+
+      datetime :history_started_at, null: false
+      datetime :history_ended_at
+      integer :history_user_id
+
+      index :history_started_at
+      index :history_ended_at
+      index :history_user_id
+      index foreign_key
+
+      ActiveRecord::Base.connection.indexes(original_table_name).each do |index|
+        index index.columns
+      end
+
+    end
+  end
+end

data/lib/historiographer/mysql_migration.rb

@@ -0,0 +1,7 @@
+require_relative "history_migration_mysql"
+
+if defined?(ActiveRecord::ConnectionAdapters::Mysql2Adapter)
+  class ActiveRecord::ConnectionAdapters::TableDefinition
+    include Historiographer::HistoryMigrationMysql
+  end
+end

data/lib/historiographer/postgres_migration.rb

@@ -0,0 +1,7 @@
+require_relative "history_migration"
+
+if defined?(ActiveRecord::ConnectionAdapters::PostgreSQL::TableDefinition)
+  class ActiveRecord::ConnectionAdapters::PostgreSQL::TableDefinition
+    include Historiographer::HistoryMigration
+  end
+end

data/lib/historiographer/safe.rb

@@ -0,0 +1,33 @@
+# Historiographer::Safe is intended to be used to migrate an existing model
+# to Historiographer, not as a long-term solution.
+#
+# Historiographer will throw an error if a model is saved without a user present,
+# unless you explicitly call save_without_history.
+#
+# Historiographer::Safe will not throw an error, but will rather produce a Rollbar,
+# which enables a programmer to find all locations that need to be migrated,
+# rather than allowing an unsafe migration to take place.
+#
+# Eventually the programmer is expected to replace Safe with Historiographer so
+# that future programmers will get an error if they try to save without user_id.
+#
+module Historiographer
+  module Safe
+    extend ActiveSupport::Concern
+
+    included do
+      include Historiographer
+
+      def should_validate_history_user_id_present?
+        false
+      end
+
+      private
+
+      def history_user_absent_action
+        Rollbar.error("history_user_id must be passed in order to save record with histories! If you are in a context with no history_user_id, explicitly call #save_without_history")
+      end
+    end
+
+  end
+end

data/lib/historiographer.rb

@@ -0,0 +1,235 @@
+require "active_support/all"
+require_relative "./historiographer/history"
+require_relative "./historiographer/postgres_migration"
+require_relative "./historiographer/safe"
+
+# Historiographer takes "histories" (think audits or snapshots) of your model whenever you make changes.
+#
+# Core business data stored in histories can never be changed or destroyed (at least not from Rails-land), offering you
+# a little more peace of mind (just a little).
+#
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+#
+# A little example:
+#
+# photo = Photo.create(file: "cool.jpg")
+# photo.histories # => [ <#PhotoHistory file: cool.jpg > ]
+#
+# photo.file = "fun.jpg"
+# photo.save!
+# photo.histories.reload # => [ <#PhotoHistory file: cool.jpg >, <#PhotoHistory file: fun.jpg> ]
+#
+# photo.histories.last.destroy! # => false
+#
+# photo.histories.last.update!(file: "bad.jpg") # => false
+#
+# photo.histories.last.file = "bad.jpg"
+# photo.histories.last.save! # => false
+#
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+#
+# How to use:
+#
+# 1) Add historiographer to your apps dependencies folder
+#
+# Ex: sudo ln -s ../../../shared/historiographer historiographer
+#
+# 2) Add historiographer to your apps gem file and bundle
+#
+# gem 'historiographer', path: 'dependencies/historiographer', require: 'historiographer'
+#
+# 3) Create a primary table
+#
+# create_table :photos do |t|
+#   t.string :file
+# end
+#
+# 4) Create history table. 't.histories' pulls in all the primary tables attributes plus a few required by historiographer.
+#
+# require "historiographer/postgres_migration"
+# class CreatePhotoHistories < ActiveRecord::Migration
+#   def change
+#     create_table :photo_histories do |t|
+#       t.histories
+#     end
+#   end
+# end
+#
+# 5) Include Historiographer in the primary class:
+#
+# class Photo < ActiveRecord::Base
+#   include Historiographer
+# end
+#
+# 6) Create a history class
+#
+# class PhotoHistory < ActiveRecord::Base (or whereever your app inherits from. Ex CPG: CpgConnection, Shoppers: ShoppersRecord, etc)
+# end
+#
+# 7) Enjoy!
+#
+module Historiographer
+  extend ActiveSupport::Concern
+
+  class HistoryUserIdMissingError < StandardError; end
+
+  UTC = Time.now.in_time_zone("UTC").time_zone
+
+  included do |base|
+    after_save :record_history, if: :should_record_history?
+    validate :validate_history_user_id_present, if: :should_validate_history_user_id_present?
+
+    def should_validate_history_user_id_present?
+      true
+    end
+
+    def validate_history_user_id_present
+      if @no_history.nil? && (!history_user_id.present? || !history_user_id.is_a?(Integer))
+        errors.add(:history_user_id, "must be an integer")
+      end
+    end
+
+    def assign_attributes(new_attributes)
+      huid = new_attributes[:history_user_id]
+
+      if huid.present?
+        self.class.nested_attributes_options.each do |association, _|
+          reflection  = self.class.reflect_on_association(association)
+          assoc_attrs = new_attributes["#{association}_attributes"]
+
+          if assoc_attrs.present?
+            if reflection.collection?
+              assoc_attrs.values.each do |hash|
+                hash.merge!(history_user_id: huid)
+              end
+            else
+              assoc_attrs.merge!(history_user_id: huid)
+            end
+          end
+        end
+      end
+
+      super
+    end
+
+    def historiographer_changes?
+      case Rails.version.to_f
+      when 0..5 then changed? && valid?
+      when 5.1..6 then saved_changes?
+      else
+        raise "Unsupported Rails version"
+      end
+    end
+    #
+    # If there are any changes, and the model is valid,
+    # and we're not force-overriding history recording,
+    # then record history after successful save.
+    #
+    def should_record_history?
+      historiographer_changes? && !@no_history
+    end
+
+    attr_accessor :history_user_id
+
+    class_name = "#{base.name}History"
+
+    if base.respond_to?(:histories)
+      raise "#{base} already has histories. Talk to Brett if this is a legit use case."
+    else
+      has_many :histories, class_name: class_name
+      has_one :current_history, -> { current }, class_name: class_name
+    end
+
+    begin
+      class_name.constantize
+    rescue
+      history_class_initializer = Class.new(ActiveRecord::Base) do
+      end
+
+      Object.const_set(class_name, history_class_initializer)
+    end
+
+    klass = class_name.constantize
+
+    klass.send(:include, Historiographer::History) unless klass.ancestors.include?(Historiographer::History)
+
+    #
+    # The acts_as_paranoid gem, which we tend to use with our History classes,
+    # uses update_columns to update deleted_at fields.
+    #
+    # In order to make sure these changes are persisted into Histories objects,
+    # we also have to record history here.
+    #
+    module UpdateColumnsWithHistory
+      def update_columns(*args)
+        opts = args.extract_options!
+        any_changes = opts.keys.reject { |k| k == "id" }.any?
+
+        transaction do
+          persisted = super(opts)
+
+          if any_changes && persisted
+            record_history
+          end
+        end
+      end
+    end
+    base.send(:prepend, UpdateColumnsWithHistory)
+
+    def save_without_history(*args, &block)
+      @no_history = true
+      save(*args, &block)
+      @no_history = false
+    end
+
+    def save_without_history!(*args, &block)
+      @no_history = true
+      save!(*args, &block)
+      @no_history = false
+    end
+
+    private
+
+    def history_user_absent_action
+      raise HistoryUserIdMissingError.new("history_user_id must be passed in order to save record with histories! If you are in a context with no history_user_id, explicitly call #save_without_user")
+    end
+
+    #
+    # Save a record of the most recent changes, with the current
+    # time as history_started_at, and the provided user as history_user_id.
+    #
+    # Find the most recent history, and update its history_ended_at timestamp
+    #
+    def record_history
+      history_user_absent_action if history_user_id.nil?
+
+      attrs         = attributes.clone
+      history_class = self.class.history_class
+      foreign_key   = history_class.history_foreign_key
+
+      now = UTC.now
+      attrs.merge!(foreign_key => attrs["id"], history_started_at: now, history_user_id: history_user_id)
+
+      attrs = attrs.except("id")
+
+      current_history = histories.where(history_ended_at: nil).order("id desc").limit(1).last
+
+      unless foreign_key.present? && history_class.present?
+        raise "Need foreign key and history class to save history!"
+      else
+        history_class.create!(attrs)
+        current_history.update!(history_ended_at: now) if current_history.present?
+      end
+    end
+  end
+
+  class_methods do
+
+    #
+    # E.g. SponsoredProductCampaign => SponsoredProductCampaignHistory
+    #
+    def history_class
+      "#{name}History".constantize
+    end
+  end
+end

data/spec/db/database.yml

@@ -0,0 +1,27 @@
+# default: &default
+#   adapter: postgresql
+#   prepared_statements: false
+#   url: "postgres://localhost/historiographer_development"
+
+# development:
+#   <<: *default
+
+# test:
+#   adapter: postgresql
+#   database: historiographer_test
+
+mysql_default: &mysql_default
+  adapter: mysql2
+  encoding: utf8
+  username: root
+  password:
+  host: 127.0.0.1
+  port: 3306
+
+development:
+  <<: *mysql_default
+  database: historiographer_development
+
+test:
+  <<: *mysql_default
+  database: historiographer_test

data/spec/db/migrate/20161121212228_create_posts.rb

@@ -0,0 +1,19 @@
+class CreatePosts < ActiveRecord::Migration[5.1]
+  def change
+    create_table :posts do |t|
+      t.string :title, null: false
+      t.text :body, null: false
+      t.integer :author_id, null: false
+      t.boolean :enabled, default: false
+      t.datetime :live_at
+      t.datetime :deleted_at
+
+      t.timestamps
+    end
+
+    add_index :posts, :author_id
+    add_index :posts, :enabled
+    add_index :posts, :live_at
+    add_index :posts, :deleted_at
+  end
+end

data/spec/db/migrate/20161121212229_create_post_histories.rb

@@ -0,0 +1,10 @@
+require "historiographer/postgres_migration"
+require "historiographer/mysql_migration"
+
+class CreatePostHistories < ActiveRecord::Migration[5.1]
+  def change
+    create_table :post_histories do |t|
+      t.histories
+    end
+  end
+end

data/spec/db/migrate/20161121212230_create_authors.rb

@@ -0,0 +1,13 @@
+class CreateAuthors < ActiveRecord::Migration[5.1]
+  def change
+    create_table :authors do |t|
+      t.string :full_name, null: false
+      t.text :bio
+      t.datetime :deleted_at
+
+      t.timestamps
+    end
+
+    add_index :authors, :deleted_at
+  end
+end

data/spec/db/migrate/20161121212231_create_author_histories.rb

@@ -0,0 +1,10 @@
+require "historiographer/postgres_migration"
+require "historiographer/mysql_migration"
+
+class CreateAuthorHistories < ActiveRecord::Migration[5.1]
+  def change
+    create_table :author_histories do |t|
+      t.histories
+    end
+  end
+end

data/spec/db/migrate/20161121212232_create_users.rb

@@ -0,0 +1,9 @@
+require "historiographer/postgres_migration"
+
+class CreateUsers < ActiveRecord::Migration[5.1]
+  def change
+    create_table :users do |t|
+      t.string :name
+    end
+  end
+end