draft_approve 0.1.0

data/lib/draft_approve/draftable/instance_methods.rb

@@ -0,0 +1,80 @@
+require 'draft_approve/persistor'
+
+module DraftApprove
+  module Draftable
+
+    # Instance methods automatically added to an ActiveRecord model when
+    # +acts_as_draftable+ is called
+    module InstanceMethods
+      ##### Basic DraftApprove instance methods #####
+
+      # Whether this object is draftable. Helper method to identify draftable
+      # objects.
+      #
+      # @return [Boolean] true
+      def draftable?
+        true
+      end
+
+      # Saves any changes to the object as a draft.
+      #
+      # This method may be called both on a new object which has not been
+      # persisted yet, and on objects which have already been persisted.
+      #
+      # @param options [Hash] the options to save the draft with
+      # @option options [Symbol] :validate whether to validate the model before
+      #   draft changes are saved, defaults to +true+
+      # @option options [Symbol] :create_method the method to use when creating
+      #   a new object from this draft, eg. +:find_or_create_by!+. This must be
+      #   a method available on the object, and must accept a hash of attribute
+      #   names to attribute values. The default is +create!+. Ignored if this
+      #   draft is for an object which has already been persisted.
+      # @option options [Symbol] :update_method the method to use when updating
+      #   an existing object from this draft, eg. +:update_columns+. This must
+      #   be a method available on the object, and must accept a hash of
+      #   attribute names to attribute values. The default is +update!+. Ignored
+      #   if this draft is for an object which has not yet been persisted.
+      #
+      # @return [Draft, nil] the +Draft+ object which was created, or +nil+ if
+      #   there were no changes to the object
+      def draft_save!(options = nil)
+        if self.new_record?
+          DraftApprove::Persistor.write_draft_from_model(Draft::CREATE, self, options)
+        else
+          DraftApprove::Persistor.write_draft_from_model(Draft::UPDATE, self, options)
+        end
+      end
+
+      # Marks this object to be destroyed when this draft change is approved.
+      #
+      # This method should only be called on objects which have already been
+      # persisted.
+      #
+      # @param options [Hash] the options to save the draft with
+      # @option options [Symbol] :delete_method the method to use to delete
+      #   the object when this draft is approved, eg. +:delete+. This must be
+      #   a method available on the object. The default is +destroy!+.
+      #
+      # @return [Draft] the +Draft+ object which was created
+      def draft_destroy!(options = nil)
+        DraftApprove::Persistor.write_draft_from_model(Draft::DELETE, self, options)
+      end
+
+      ##### Additional convenience DraftApprove instance methods #####
+
+      # Updates an existing object with the given attributes, and saves the
+      # updates as a draft.
+      #
+      # @param attributes [Hash] a hash of attribute names to attribute values,
+      #   like the hash expected by the ActiveRecord +update+ / +update!+
+      #   methods
+      #
+      # @return [Draft, nil] the +Draft+ object which was created, or +nil+ if
+      #   there were no changes to the object
+      def draft_update!(attributes)
+        self.assign_attributes(attributes)
+        self.draft_save!
+      end
+    end
+  end
+end

data/lib/draft_approve/errors.rb

@@ -0,0 +1,19 @@
+module DraftApprove
+  module Errors
+    class DraftTransactionError < StandardError; end
+    class NestedDraftTransactionError < DraftTransactionError; end
+    class NoDraftTransactionError < DraftTransactionError; end
+
+    class DraftSaveError < StandardError; end
+    class ExistingDraftError < DraftSaveError; end
+    class AlreadyPersistedModelError < DraftSaveError; end
+    class UnpersistedModelError < DraftSaveError; end
+
+    class ChangeSerializationError < StandardError; end
+    class AssociationUnsavedError < ChangeSerializationError; end
+
+    class ApplyDraftChangesError < StandardError; end
+    class NoDraftableError < ApplyDraftChangesError; end
+    class PriorDraftNotAppliedError < ApplyDraftChangesError; end
+  end
+end

data/lib/draft_approve/models/draft.rb

@@ -0,0 +1,75 @@
+# @note It is strongly recommended that you do not directly create +Draft+
+#   objects, and instead use the supported public interface for doing so. See
+#   +DraftApprove::Draftable::ClassMethods+,
+#   +DraftApprove::Draftable::InstanceMethods+, and the README docs for this.
+#
+# ActiveRecord model for persisting data about draft changes.
+#
+# Each +Draft+ must be linked to a +DraftTransaction+, and must have a
+# +draft_action_type+ which specifies whether this draft is to create a new
+# record, update a record, or delete a record.
+#
+# If the draft is to update or delete an existing record in the database, the
+# +Draft+ will also have a link to the +acts_as_draftable+ instance to which it
+# relates, via the polymorphic +draftable+ association.
+#
+# Linking to the +acts_as_draftable+ instance is not possible for drafts which
+# create new records, since the new record does not yet exist in the database!
+# In these cases, the +draftable_type+ column is still set to the name of the
+# class which is to be created, but the +draftable_id+ is +nil+.
+#
+# The +draft_changes+ attribute is a serialized representation of the draft
+# changes. The representation is delegated to a +DraftApprove::Serialization+
+# module. At present, there is only a JSON implementation, suitable for use with
+# PostgreSQL databases.
+#
+# Note that saving 'no-op' +Draft+s is generally avoided by this library
+# (specifically by the +DraftApprove::Persistor+ class).
+#
+# @see DraftTransaction
+# @see DraftApprove::Draftable::ClassMethods
+# @see DraftApprove::Draftable::InstanceMethods
+class Draft < ActiveRecord::Base
+  # IMPORTANT NOTE: These constants are written to the database, so cannot be
+  # updated without requiring a migration of existing draft data
+  CREATE = 'create'.freeze
+  UPDATE = 'update'.freeze
+  DELETE = 'delete'.freeze
+
+  belongs_to :draft_transaction
+  belongs_to :draftable, polymorphic: true, optional: true
+
+  validates :draft_action_type, inclusion: {
+    in: [CREATE, UPDATE, DELETE],
+    message: "%{value} is not a valid Draft.draft_action_type"
+  }
+
+  scope :pending_approval, -> { joins(:draft_transaction).merge(DraftTransaction.pending_approval) }
+  scope :approved, -> { joins(:draft_transaction).merge(DraftTransaction.approved) }
+  scope :rejected, -> { joins(:draft_transaction).merge(DraftTransaction.rejected) }
+  scope :approval_error, -> { joins(:draft_transaction).merge(DraftTransaction.approval_error) }
+
+  # @return [Boolean] +true+ if this +Draft+ is to create a new record, +false+
+  #   otherwise
+  def create?
+    draft_action_type == CREATE
+  end
+
+  # @return [Boolean] +true+ if this +Draft+ is to update an existing record,
+  #   +false+ otherwise
+  def update?
+    draft_action_type == UPDATE
+  end
+
+  # @return [Boolean] +true+ if this +Draft+ is to delete an existing record,
+  #   +false+ otherwise
+  def delete?
+    draft_action_type == DELETE
+  end
+
+  # Apply the changes in this draft, writing them to the database
+  # @api private
+  def apply_changes!
+    DraftApprove::Persistor.write_model_from_draft(self)
+  end
+end

data/lib/draft_approve/models/draft_transaction.rb

@@ -0,0 +1,109 @@
+# @note It is strongly recommended that you do not directly create
+#   +DraftTransaction+ objects, and instead use the supported public interface
+#   for doing so. See +DraftApprove::Draftable::ClassMethods+ and the README
+#   docs for this.
+#
+# ActiveRecord model for persisting data about a group of draft changes which
+# should be approved or rejected as a single, transactional group.
+#
+# Each +DraftTransaction+ has many linked +Draft+ objects.
+#
+# When a +DraftTransaction+ is first created, it has +status+ of
+# +pending_approval+. The changes should then be reviewed and either approved or
+# rejected.
+#
+# +DraftTransaction+ objects also have optional attribute for storing who or
+# what created the transaction and the group of draft changes (+created_by+
+# attribute), who or what reviewed the changes (+reviewed_by+ attribute), and
+# the reason given for approving or rejecting the changes (+review_reason+
+# attribute), and finally the stack trace of any error which occurred during
+# the process of applying the changes (+error+ attribute).
+#
+# Arbitrary extra data can also be stored in the +extra_data+ attribute.
+#
+# Note that saving 'no-op' +DraftTransaction+s is generally avoided by this
+# library (specifically by the +DraftApprove::Transaction+ class).
+#
+# @see Draft
+# @see DraftApprove::Draftable::ClassMethods
+class DraftTransaction < ActiveRecord::Base
+  # IMPORTANT NOTE: These constants are written to the database, so cannot be
+  # updated without requiring a migration of existing draft data
+  PENDING_APPROVAL = 'pending_approval'.freeze
+  APPROVED = 'approved'.freeze
+  REJECTED = 'rejected'.freeze
+  APPROVAL_ERROR = 'approval_error'.freeze
+
+  has_many :drafts
+
+  validates :status, inclusion: {
+    in: [PENDING_APPROVAL, APPROVED, REJECTED, APPROVAL_ERROR],
+    message: "%{value} is not a valid DraftTransaction.status"
+  }
+
+  scope :pending_approval, -> { where(status: PENDING_APPROVAL) }
+  scope :approved, -> { where(status: APPROVED) }
+  scope :rejected, -> { where(status: REJECTED) }
+  scope :approval_error, -> { where(status: APPROVAL_ERROR) }
+
+  # Approve all changes in this +DraftTransaction+ and immediately apply them
+  # to the database.
+  #
+  # Note that applying the changes occurs within a database transaction.
+  #
+  # @param reviewed_by [String] the user or process which approved these changes
+  # @param review_reason [String] the reason for approving these changes
+  #
+  # @return [Boolean] +true+ if the changes were successfully applied
+  def approve_changes!(reviewed_by: nil, review_reason: nil)
+    begin
+      ActiveRecord::Base.transaction do
+        self.lock!  # Avoid multiple threads applying changes concurrently
+        return false unless self.status == PENDING_APPROVAL
+
+        drafts.order(:created_at, :id).each do |draft|
+          draft.apply_changes!
+        end
+
+        self.update!(status: APPROVED, reviewed_by: reviewed_by, review_reason: review_reason)
+        return true
+      end
+    rescue StandardError => e
+      # Log the error in the database table and re-raise
+      self.update!(status: APPROVAL_ERROR, error: "#{e.inspect}\n#{e.backtrace.join("\n")}")
+      raise
+    end
+  end
+
+  # Reject all changes in this +DraftTransaction+.
+  #
+  # @param reviewed_by [String] the user or process which rejected these changes
+  # @param review_reason [String] the reason for rejecting these changes
+  #
+  # @return [Boolean] +true+ if the changes were successfully rejected
+  def reject_changes!(reviewed_by: nil, review_reason: nil)
+    self.update!(status: REJECTED, reviewed_by: reviewed_by, review_reason: review_reason)
+    return true
+  end
+
+  # Get a +DraftChangesProxy+ for the given object in the scope of this
+  # +DraftTransaction+.
+  #
+  # @param object [Object] the +Draft+ or +acts_as_draftable+ object to
+  #   create a +DraftChangesProxy+ for
+  #
+  # @return [DraftChangesProxy] a proxy to get changes drafted to the given
+  #   object and related objects, within the scope of this +DraftTransaction+
+  #
+  # @see DraftApprove::DraftChangesProxy
+  def draft_proxy_for(object)
+    serialization_module.get_draft_changes_proxy.new(object, self)
+  end
+
+  # @return the module used for serialization by this +DraftTransaction+.
+  #
+  # @api private
+  def serialization_module
+    Object.const_get(self.serialization)
+  end
+end

data/lib/draft_approve/persistor.rb

@@ -0,0 +1,167 @@
+require 'draft_approve/errors'
+require 'draft_approve/models/draft'
+require 'draft_approve/serialization/json'
+
+module DraftApprove
+
+  # Logic for writing a +Draft+ to the database, and for applying changes
+  # contained within a single +Draft+ and saving them to the database.
+  #
+  # @api private
+  class Persistor
+    DEFAULT_CREATE_METHOD = 'create!'.freeze
+    DEFAULT_UPDATE_METHOD = 'update!'.freeze
+    DEFAULT_DELETE_METHOD = 'destroy!'.freeze
+    private_constant :DEFAULT_CREATE_METHOD, :DEFAULT_UPDATE_METHOD, :DEFAULT_DELETE_METHOD
+
+    # IMPORTANT NOTE: These constants are written to the database, so cannot be
+    # updated without requiring a migration of existing draft data. Such a
+    # migration may be very slow, since these constants are embedded in the
+    # JSON generated by this serializer!
+    CREATE_METHOD = 'create_method'.freeze
+    UPDATE_METHOD = 'update_method'.freeze
+    DELETE_METHOD = 'delete_method'.freeze
+    private_constant :CREATE_METHOD, :UPDATE_METHOD, :DELETE_METHOD
+
+    # Write a +Draft+ object to the database to persist any changes to the
+    # given model.
+    #
+    # @param action_type [String] the type of action this draft will represent -
+    #   +CREATE+, +UPDATE+, or +DELETE+
+    # @param model [Object] the +acts_as_draftable+ ActiveRecord model whose
+    #   changes will be saved to the database
+    # @param options [Hash] the options to use when saving this draft, see
+    #   +DraftApprove::Draftable::InstanceMethods#draft_save!+ and
+    #   +DraftApprove::Draftable::InstanceMethods#draft_destroy!+ for details of
+    #   valid options
+    #
+    # @return [Draft, false] the +Draft+ record which was created, or +false+ if
+    #   there were no changes (ie. the result would have been a 'no-op' change)
+    #
+    # @see DraftApprove::Draftable::InstanceMethods#draft_save!
+    # @see DraftApprove::Draftable::InstanceMethods#draft_destroy!
+    def self.write_draft_from_model(action_type, model, options = nil)
+      raise(ArgumentError, 'model argument must be present') unless model.present?
+
+      if validate_model?(options) && model.invalid?
+        raise(ActiveRecord::RecordInvalid, model)
+      end
+
+      DraftApprove::Transaction.ensure_in_draft_transaction do
+        # Now we're in a Transaction, ensure we don't get multiple drafts for the same object
+        if model.persisted? && Draft.pending_approval.where(draftable: model).count > 0
+          raise(DraftApprove::Errors::ExistingDraftError, "#{model} has existing draft")
+        end
+
+        case action_type
+        when Draft::CREATE
+          raise(DraftApprove::Errors::AlreadyPersistedModelError, "#{model} is already persisted") if model.persisted?
+          draftable_type = model.class.name
+          draftable_id = nil
+        when Draft::UPDATE
+          raise(DraftApprove::Errors::UnpersistedModelError, "#{model} isn't persisted") unless model.persisted?
+          draftable_type = model.class.name
+          draftable_id = model.id
+        when Draft::DELETE
+          raise(DraftApprove::Errors::UnpersistedModelError, "#{model} isn't persisted") unless model.persisted?
+          draftable_type = model.class.name
+          draftable_id = model.id
+        else
+          raise(ArgumentError, "Unknown draft_action_type #{action_type}")
+        end
+
+        draft_transaction = DraftApprove::Transaction.current_draft_transaction!
+        draft_options = sanitize_options_for_db(options)
+        serializer = serializer_class(draft_transaction)
+        changes = serializer.changes_for_model(model)
+
+        # Don't write no-op updates!
+        return false if changes.empty? && action_type == Draft::UPDATE
+
+        return model.draft_pending_approval = Draft.create!(
+          draft_transaction: draft_transaction,
+          draftable_type: draftable_type,
+          draftable_id: draftable_id,
+          draft_action_type: action_type,
+          draft_changes: changes,
+          draft_options: draft_options
+        )
+      end
+    end
+
+    # Write the changes represented by the given +Draft+ object to the database.
+    #
+    # Depending upon the type of +Draft+, this method may create a new record in
+    # the database, update an existing record, or delete a record.
+    #
+    # @param draft [Draft] the +Draft+ object whose changes should be applied
+    #   and persisted to the database
+    #
+    # @return [Object] the +acts_as_draftable+ ActiveRecord model which has been
+    #   created, updated, or deleted
+    def self.write_model_from_draft(draft)
+      serializer = serializer_class(draft.draft_transaction)
+      new_values_hash = serializer.new_values_for_draft(draft)
+      options = draft.draft_options || {}
+
+      case draft.draft_action_type
+      when Draft::CREATE
+        raise(DraftApprove::Errors::NoDraftableError, "No draftable_type for #{draft}") if draft.draftable_type.blank?
+
+        create_method = (options.include?(CREATE_METHOD) ? options[CREATE_METHOD] : DEFAULT_CREATE_METHOD)
+
+        model_class = Object.const_get(draft.draftable_type)
+        model = model_class.send(create_method, new_values_hash)
+
+        # We've only just persisted the model, the draft can't have referenced it before!
+        draft.update!(draftable: model)
+
+        return model
+      when Draft::UPDATE
+        raise(DraftApprove::Errors::NoDraftableError, "No draftable for #{draft}") if draft.draftable.blank?
+
+        update_method = (options.include?(UPDATE_METHOD) ? options[UPDATE_METHOD] : DEFAULT_UPDATE_METHOD)
+
+        model = draft.draftable
+        model.send(update_method, new_values_hash)
+        return model
+      when Draft::DELETE
+        raise(DraftApprove::Errors::NoDraftableError, "No draftable for #{draft}") if draft.draftable.blank?
+
+        delete_method = (options.include?(DELETE_METHOD) ? options[DELETE_METHOD] : DEFAULT_DELETE_METHOD)
+
+        model = draft.draftable
+        model.send(delete_method)
+        return model
+      else
+        raise(ArgumentError, "Unknown draft_action_type #{draft.draft_action_type}")
+      end
+    end
+
+    private
+
+    # Helper to determine whether to validate a model before writing a draft
+    def self.validate_model?(options)
+      options ||= {}
+      options.fetch(:validate, true)
+    end
+
+    # Helper to get the serialization class to use
+    def self.serializer_class(draft_transaction)
+      draft_transaction.serialization_module.get_serializer
+    end
+
+    # Helper to remove invalid options before they get persisted to the database
+    def self.sanitize_options_for_db(options)
+      return nil if !options || options.empty?
+
+      draft_options_keys = [CREATE_METHOD, UPDATE_METHOD, DELETE_METHOD]
+
+      accepted_options = options.each_with_object({}) do |(key, value), accepted_opts|
+        accepted_opts[key.to_s] = value if draft_options_keys.include?(key.to_s)
+      end
+
+      return (accepted_options.empty? ? nil : accepted_options)
+    end
+  end
+end