userstamper 4.0.0

data/lib/userstamper.rb

@@ -0,0 +1,23 @@
+require "active_support"
+require "active_support/rails"
+require "active_support/concern"
+
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+module Userstamper
+  # Retrieves the configuration for the Userstamper gem.
+  # @return [Userstamper::Configuration]
+  def self.config
+    Configuration
+  end
+
+  # Configures the gem.
+  # @yield [Userstamper::Configuration] The configuration for the gem.
+  def self.configure
+    yield config
+  end
+end
+
+require "userstamper/railtie" if defined?(Rails::Railtie)

data/lib/userstamper/configuration.rb

@@ -0,0 +1,40 @@
+module Userstamper::Configuration
+  # !@attribute [r] default_stamper
+  #   Determines the default model used to stamp other models.
+  #
+  #   By default, this is set to +'User'+.
+  def self.default_stamper
+    ActiveRecord::Base.stamper_class_name
+  end
+
+  # !@attribute [rw] default_stamper
+  # @see {.default_stamper}
+  def self.default_stamper=(stamper)
+    ActiveRecord::Base.stamper_class_name = stamper
+  end
+  self.default_stamper = 'User'.freeze
+
+  # @!attribute [r] default_stamper_class
+  #   Determines the default model used to stamp other models.
+  def self.default_stamper_class
+    ActiveRecord::Base.stamper_class
+  end
+
+  # !@attribute [rw] creator_attribute
+  #   Determines the name of the column in the database which stores the name of the creator.
+  #
+  #   Override the attribute by using the stampable class method within a model.
+  #
+  #   By default, this is set to +:creator_id+.
+  mattr_accessor :creator_attribute
+  self.creator_attribute = :creator_id
+
+  # !@attribute [rw] updater_attribute
+  #   Determines the name of the column in the database which stores the name of the updater.
+  #
+  #   Override the attribute by using the stampable class method within a model.
+  #
+  #   By default, this is set to +:updater_id+.
+  mattr_accessor :updater_attribute
+  self.updater_attribute = :updater_id
+end

data/lib/userstamper/controller_concern.rb

@@ -0,0 +1,44 @@
+# The +Userstamper::Controller+ module, when included into a controller, adds an +before_action+
+# callback (named +set_stamper+) and an +after_action+ callback (named +reset_stamper+). These
+# methods assume a couple of things, but can be re-implemented in your controller to better suit
+# your application.
+#
+# See the documentation for `set_stamper` and `reset_stamper` for specific implementation details.
+module Userstamper::ControllerConcern
+  extend ActiveSupport::Concern
+
+  included do
+    around_action :with_stamper
+  end
+
+  private
+
+  # This {#with_stamper} method sets the stamper for the duration of the action. This ensures
+  # that exceptions raised within the controller action would properly restore the previous stamper.
+  #
+  # TODO: Remove set_stamper/reset_stamper
+  def with_stamper
+    set_stamper
+    yield
+  ensure
+    reset_stamper
+  end
+
+  # The {#set_stamper} method as implemented here assumes a couple of things. First, that you are
+  # using a +User+ model as the stamper and second that your controller has a +current_user+
+  # method that contains the currently logged in stamper. If either of these are not the case in
+  # your application you will want to manually add your own implementation of this method to the
+  # private section of your +ApplicationController+
+  def set_stamper
+    @_userstamp_stamper = Userstamper.config.default_stamper_class.stamper
+    Userstamper.config.default_stamper_class.stamper = current_user
+  end
+
+  # The {#reset_stamper} method as implemented here assumes that a +User+ model is being used as
+  # the stamper. If this is not the case then you will need to manually add your own
+  # implementation of this method to the private section of your +ApplicationController+
+  def reset_stamper
+    Userstamper.config.default_stamper_class.stamper = @_userstamp_stamper
+    @_userstamp_stamper = nil
+  end
+end

data/lib/userstamper/migration_concern.rb

@@ -0,0 +1,9 @@
+module Userstamper::MigrationConcern
+  extend ActiveSupport::Concern
+
+  def userstamps(*args)
+    config = Userstamper.config
+    column(config.creator_attribute, :integer, *args)
+    column(config.updater_attribute, :integer, *args)
+  end
+end

data/lib/userstamper/model_concern.rb

@@ -0,0 +1,6 @@
+module Userstamper::ModelConcern
+  extend ActiveSupport::Concern
+
+  include Userstamper::Stampable
+  include Userstamper::Stamper
+end

data/lib/userstamper/railtie.rb

@@ -0,0 +1,15 @@
+module Userstamper
+  class Railtie < Rails::Railtie
+    initializer "userstamper.action_controller" do
+      ActiveSupport.on_load(:action_controller_base) do
+        include Userstamper::ControllerConcern
+      end
+
+      ActiveSupport.on_load(:active_record) do
+        include Userstamper::ModelConcern
+
+        ActiveRecord::ConnectionAdapters::TableDefinition.send(:include, Userstamper::MigrationConcern)
+      end
+    end
+  end
+end

data/lib/userstamper/stampable.rb

@@ -0,0 +1,106 @@
+# Extends the stamping functionality of ActiveRecord by automatically recording the model
+# responsible for creating, updating the current object. See the +Stamper+ and
+# +ControllerAdditions+ modules for further documentation on how the entire process works.
+module Userstamper::Stampable
+  extend ActiveSupport::Concern
+
+  included do
+    # Should ActiveRecord record userstamps? Defaults to true.
+    class_attribute  :record_userstamp
+    self.record_userstamp = true
+
+    class_attribute  :stamper_class_name
+
+    before_validation :set_updater_attribute, if: :record_userstamp
+    before_validation :set_creator_attribute, on: :create, if: :record_userstamp
+    before_save :set_updater_attribute, if: :record_userstamp
+    before_create :set_creator_attribute, if: :record_userstamp
+  end
+
+  module ClassMethods
+    def columns(*)
+      columns = super
+      return columns if defined?(@stamper_initialized) && @stamper_initialized
+
+      add_userstamp_associations({})
+      columns
+    end
+
+    # This method customizes how the gem functions. For example:
+    #
+    #   class Post < ActiveRecord::Base
+    #     stampable stamper_class_name: Person.name
+    #   end
+    #
+    # the gem configuration.
+    def stampable(options = {})
+      self.stamper_class_name = options.delete(:stamper_class_name) if options.key?(:stamper_class_name)
+
+      add_userstamp_associations(options)
+    end
+
+    # Temporarily allows you to turn stamping off. For example:
+    #
+    #   Post.without_stamps do
+    #     post = Post.find(params[:id])
+    #     post.update_attributes(params[:post])
+    #     post.save
+    #   end
+    def without_stamps
+      original_value = self.record_userstamp
+      self.record_userstamp = false
+      yield
+    ensure
+      self.record_userstamp = original_value
+    end
+
+    def stamper_class #:nodoc:
+      stamper_class_name.to_s.camelize.constantize rescue nil
+    end
+
+    private
+
+    # Defines the associations for Userstamper.
+    def add_userstamp_associations(options)
+      @stamper_initialized = true
+      Userstamper::Utilities.remove_association(self, :creator)
+      Userstamper::Utilities.remove_association(self, :updater)
+
+      associations = Userstamper::Utilities.available_association_columns(self)
+      return if associations.nil?
+
+      config = Userstamper.config
+      klass = stamper_class.try(:name)
+      relation_options = options.reverse_merge(class_name: klass)
+
+      belongs_to :creator, relation_options.reverse_merge(foreign_key: config.creator_attribute, required: false) if associations.first
+      belongs_to :updater, relation_options.reverse_merge(foreign_key: config.updater_attribute, required: false) if associations.second
+    end
+  end
+
+  private
+
+  def has_stamper?
+    !self.class.stamper_class.nil? && !self.class.stamper_class.stamper.nil?
+  end
+
+  def set_creator_attribute
+    return unless has_stamper?
+
+    creator_association = self.class.reflect_on_association(:creator)
+    return unless creator_association
+    return if creator.present?
+
+    Userstamper::Utilities.assign_stamper(self, creator_association)
+  end
+
+  def set_updater_attribute
+    return unless has_stamper?
+
+    updater_association = self.class.reflect_on_association(:updater)
+    return unless updater_association
+    return if !new_record? && !changed?
+
+    Userstamper::Utilities.assign_stamper(self, updater_association)
+  end
+end

data/lib/userstamper/stamper.rb

@@ -0,0 +1,54 @@
+module Userstamper::Stamper
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+    def model_stamper
+      # don't allow multiple calls
+      return if singleton_class.included_modules.include?(InstanceMethods)
+      extend Userstamper::Stamper::InstanceMethods
+    end
+  end
+
+  module InstanceMethods
+    # Used to set the current stamper for this model.
+    #
+    # @overload stamper=(object_id)
+    #   @param [Fixnum] object_id The ID of the stamper.
+    #   @return [Fixnum]
+    # @overload stamper=(object)
+    #   @param [ActiveRecord::Base] object The stamper object.
+    #   @return [ActiveRecord::Base]
+    def stamper=(object)
+      Thread.current[stamper_identifier] = object
+    end
+
+    # Retrieves the existing stamper.
+    def stamper
+      Thread.current[stamper_identifier]
+    end
+
+    # Sets the stamper back to +nil+ to prepare for the next request.
+    def reset_stamper
+      self.stamper = nil
+    end
+
+    # For the duration that execution is within the provided block, the stamper for this class
+    # would be the specified value.
+    #
+    # This replaces the {#stamper=} and {#reset_stamper} pair because this guarantees exception
+    # safety.
+    def with_stamper(stamper)
+      old_stamper = self.stamper
+      self.stamper = stamper
+      yield
+    ensure
+      self.stamper = old_stamper
+    end
+
+    private
+
+    def stamper_identifier
+      "#{self.to_s.downcase}_#{self.object_id}_stamper"
+    end
+  end
+end

data/lib/userstamper/utilities.rb

@@ -0,0 +1,57 @@
+module Userstamper::Utilities
+  # Removes the association methods from the model.
+  #
+  # @param [Class] model The model to remove methods from.
+  # @param [Symbol] association The name of the association to remove.
+  # @return [void]
+  def self.remove_association(model, association)
+    methods = [
+      association,
+      "#{association}=",
+      "build_#{association}",
+      "create_#{association}",
+      "create_#{association}!"
+    ]
+
+    model.generated_association_methods.module_eval do
+      methods.each do |method|
+        remove_possible_method(method)
+      end
+    end
+  end
+
+  # Obtains the creator/updater columns which are present in the model.
+  #
+  # @param [Class] model The model to query.
+  # @return [nil|Array<(bool, bool, bool)>] Nil if the model does not have a table defined.
+  #   Otherwise, a tuple of booleans indicating the presence of the created, updated columns.
+  def self.available_association_columns(model)
+    return nil if model.name.nil? || model.table_name.empty?
+    columns = Set[*model.column_names]
+    config = Userstamper.config
+
+    [config.creator_attribute.present? && columns.include?(config.creator_attribute.to_s),
+     config.updater_attribute.present? && columns.include?(config.updater_attribute.to_s)]
+  rescue ActiveRecord::StatementInvalid => _
+    nil
+  end
+
+  # Assigns the stamper to the given association reflection in the record.
+  #
+  # If the stamper is a record, then it is assigned to the association; if it is a number, then it
+  # is assigned to the foreign key.
+  #
+  # @param [ActiveRecord::Base] record The record to assign.
+  # @param [ActiveRecord::Reflection] association The association to assign
+  def self.assign_stamper(record, association)
+    stamp_value = record.class.stamper_class.stamper
+    attribute =
+      if stamp_value.is_a?(ActiveRecord::Base)
+        association.name
+      else
+        association.foreign_key
+      end
+
+    record.send("#{attribute}=", stamp_value)
+  end
+end

data/spec/controllers/posts_controller_spec.rb

@@ -0,0 +1,44 @@
+require 'rails_helper'
+
+RSpec.describe PostsController, type: :controller do
+  controller do
+  end
+
+  before(:each) { define_first_post }
+
+  context 'when updating a Post' do
+    it 'sets the correct updater' do
+      request.session  = { person_id: @delynn.id }
+      post :update, params: { id: @first_post.id, post: { title: 'Different' } }
+
+      expect(response.status).to eq(200)
+      expect(controller.instance_variable_get(:@post).title).to eq('Different')
+      expect(controller.instance_variable_get(:@post).updater).to eq(@delynn)
+    end
+  end
+
+  context 'when handling multiple requests' do
+    def simulate_second_request
+      old_request_session = request.session
+      request.session = { person_id: @nicole.id }
+
+      post :update, params: { id: @first_post.id, post: { title: 'Different Second'} }
+      expect(controller.instance_variable_get(:@post).updater).to eq(@nicole)
+    ensure
+      request.session = old_request_session
+    end
+
+    it 'sets the correct updater' do
+      request.session = { person_id: @delynn.id }
+      get :edit, params: { id: @first_post.id }
+      expect(response.status).to eq(200)
+
+      simulate_second_request
+
+      post :update, params: { id: @first_post.id, post: { title: 'Different' } }
+      expect(response.status).to eq(200)
+      expect(controller.instance_variable_get(:@post).title).to eq('Different')
+      expect(controller.instance_variable_get(:@post).updater).to eq(@delynn)
+    end
+  end
+end

data/spec/controllers/users_controller_spec.rb

@@ -0,0 +1,50 @@
+require 'rails_helper'
+
+RSpec.describe UsersController, type: :controller do
+  controller do
+  end
+
+  context 'when updating a User' do
+    it 'sets the correct updater' do
+      request.session = { user_id: @hera.id }
+      patch :update, params: { id: @hera.id, user: { name: 'Different'} }
+
+      expect(response.status).to eq(200)
+      expect(controller.instance_variable_get(:@user).name).to eq('Different')
+      expect(controller.instance_variable_get(:@user).updater).to eq(@hera)
+    end
+  end
+
+  context 'when handling multiple requests' do
+    def simulate_second_request
+      old_request_session = request.session
+      request.session = { user_id: @zeus.id }
+
+      post :update, params: { id: @hera.id, user: { name: 'Different Second' } }
+      expect(controller.instance_variable_get(:@user).updater).to eq(@zeus)
+    ensure
+      request.session = old_request_session
+    end
+
+    it 'sets the correct updater' do
+      request.session = { user_id: @hera.id }
+      get :edit, params: { id: @hera.id }
+      expect(response.status).to eq(200)
+
+      simulate_second_request
+    end
+  end
+
+  context 'when the handler raises an exception' do
+    before { @stamper = User.stamper }
+    it 'restores the correct stamper' do
+      begin
+        request.session = { user_id: @zeus.id }
+        post :create
+      rescue
+      end
+
+      expect(User.stamper).to be(@stamper)
+    end
+  end
+end