attr_masker 0.1.0 → 0.3.1

data/gemfiles/common.gemfile

@@ -0,0 +1,4 @@
+eval_gemfile "../Gemfile"
+
+gem "codecov", require: false
+gem "simplecov", require: false

data/lib/attr_masker.rb

@@ -1,227 +1,23 @@
 # (c) 2017 Ribose Inc.
 #
 
+require "ruby-progressbar"
+
 # Adds attr_accessors that mask an object's attributes
 module AttrMasker
   autoload :Version, "attr_masker/version"
+  autoload :Attribute, "attr_masker/attribute"
+  autoload :Model, "attr_masker/model"
 
   autoload :Error, "attr_masker/error"
   autoload :Performer, "attr_masker/performer"
 
   module Maskers
     autoload :Replacing, "attr_masker/maskers/replacing"
-    autoload :SIMPLE, "attr_masker/maskers/simple"
+    autoload :Simple, "attr_masker/maskers/simple"
   end
 
   require "attr_masker/railtie" if defined?(Rails)
-  def self.extended(base) # :nodoc:
-    base.class_eval do
-
-      # Only include the dangerous instance methods during the Rake task!
-      include InstanceMethods
-      attr_writer :attr_masker_options
-      @attr_masker_options, @masker_attributes = {}, {}
-    end
-  end
-
-  # Generates attr_accessors that mask attributes transparently
-  #
-  # Options (any other options you specify are passed to the masker's mask
-  # methods)
-  #
-  #   :marshal          => If set to true, attributes will be marshaled as well as masker. This is useful if you're planning
-  #                        on masking something other than a string. Defaults to false unless you're using it with ActiveRecord
-  #                        or DataMapper.
-  #
-  #   :marshaler        => The object to use for marshaling. Defaults to Marshal.
-  #
-  #   :dump_method      => The dump method name to call on the <tt>:marshaler</tt> object to. Defaults to 'dump'.
-  #
-  #   :load_method      => The load method name to call on the <tt>:marshaler</tt> object. Defaults to 'load'.
-  #
-  #   :masker           => The object to use for masking. It must respond to +#mask+. Defaults to AttrMasker::Maskers::Simple.
-  #
-  #   :if               => Attributes are only masker if this option evaluates to true. If you pass a symbol representing an instance
-  #                        method then the result of the method will be evaluated. Any objects that respond to <tt>:call</tt> are evaluated as well.
-  #                        Defaults to true.
-  #
-  #   :unless           => Attributes are only masker if this option evaluates to false. If you pass a symbol representing an instance
-  #                        method then the result of the method will be evaluated. Any objects that respond to <tt>:call</tt> are evaluated as well.
-  #                        Defaults to false.
-  #
-  # You can specify your own default options
-  #
-  #   class User
-  #     # now all attributes will be encoded and marshaled by default
-  #     attr_masker_options.merge!(:marshal => true, :some_other_option => true)
-  #     attr_masker :configuration
-  #   end
-  #
-  #
-  # Example
-  #
-  #   class User
-  #     attr_masker :email, :credit_card
-  #     attr_masker :configuration, :marshal => true
-  #   end
-  #
-  #   @user = User.new
-  #   @user.masker_email # nil
-  #   @user.email? # false
-  #   @user.email = 'test@example.com'
-  #   @user.email? # true
-  #   @user.masker_email # returns the masker version of 'test@example.com'
-  #
-  #   @user.configuration = { :time_zone => 'UTC' }
-  #   @user.masker_configuration # returns the masker version of configuration
-  #
-  #   See README for more examples
-  def attr_masker(*attributes)
-    options = {
-      :if               => true,
-      :unless           => false,
-      :column_name      => nil,
-      :marshal          => false,
-      :marshaler        => Marshal,
-      :dump_method      => "dump",
-      :load_method      => "load",
-      :masker           => AttrMasker::Maskers::SIMPLE,
-    }.merge!(attr_masker_options).merge!(attributes.last.is_a?(Hash) ? attributes.pop : {})
-
-    attributes.each do |attribute|
-      masker_attributes[attribute.to_sym] = options.merge(attribute: attribute.to_sym)
-    end
-  end
-
-  # Default options to use with calls to <tt>attr_masker</tt>
-  # XXX:Keep
-  #
-  # It will inherit existing options from its superclass
-  def attr_masker_options
-    @attr_masker_options ||= superclass.attr_masker_options.dup
-  end
-
-  # Checks if an attribute is configured with <tt>attr_masker</tt>
-  # XXX:Keep
-  #
-  # Example
-  #
-  #   class User
-  #     attr_accessor :name
-  #     attr_masker :email
-  #   end
-  #
-  #   User.attr_masker?(:name)  # false
-  #   User.attr_masker?(:email) # true
-  def attr_masker?(attribute)
-    masker_attributes.has_key?(attribute.to_sym)
-  end
-
-  # masks a value for the attribute specified
-  # XXX:modify
-  #
-  # Example
-  #
-  #   class User
-  #     attr_masker :email
-  #   end
-  #
-  #   masker_email = User.mask(:email, 'test@example.com')
-  def mask(attribute, value, options = {})
-    options = masker_attributes[attribute.to_sym].merge(options)
-    # if options[:if] && !options[:unless] && !value.nil? && !(value.is_a?(String) && value.empty?)
-    if options[:if] && !options[:unless]
-      value = options[:marshal] ? options[:marshaler].send(options[:dump_method], value) : value.to_s
-      masker_value = options[:masker].call(options.merge!(value: value))
-      masker_value
-    else
-      value
-    end
-  end
-
-  # Contains a hash of masker attributes with virtual attribute names as keys
-  # and their corresponding options as values
-  # XXX:Keep
-  #
-  # Example
-  #
-  #   class User
-  #     attr_masker :email
-  #   end
-  #
-  #   User.masker_attributes # { :email => { :attribute => 'masker_email' } }
-  def masker_attributes
-    @masker_attributes ||= superclass.masker_attributes.dup
-  end
-
-  # Forwards calls to :mask_#{attribute} to the corresponding mask method
-  # if attribute was configured with attr_masker
-  #
-  # Example
-  #
-  #   class User
-  #     attr_masker :email
-  #   end
-  #
-  #   User.mask_email('SOME_masker_EMAIL_STRING')
-  def method_missing(method, *arguments, &block)
-    if method.to_s =~ /^mask_(.+)$/ && attr_masker?($1)
-      send(:mask, $1, *arguments)
-    else
-      super
-    end
-  end
-
-  module InstanceMethods
-
-    # masks a value for the attribute specified using options evaluated in the current object's scope
-    #
-    # Example
-    #
-    #  class User
-    #    attr_accessor :secret_key
-    #    attr_masker :email
-    #
-    #    def initialize(secret_key)
-    #      self.secret_key = secret_key
-    #    end
-    #  end
-    #
-    #  @user = User.new('some-secret-key')
-    #  @user.mask(:email, 'test@example.com')
-    def mask(attribute, value=nil)
-      value = self.send(attribute) if value.nil?
-      self.class.mask(attribute, value, evaluated_attr_masker_options_for(attribute))
-    end
-
-    protected
-
-      # Returns attr_masker options evaluated in the current object's scope for the attribute specified
-      # XXX:Keep
-      def evaluated_attr_masker_options_for(attribute)
-        self.class.masker_attributes[attribute.to_sym].inject({}) do |hash, (option, value)|
-          if %i[if unless].include?(option)
-            hash.merge!(option => evaluate_attr_masker_option(value))
-          else
-            hash.merge!(option => value)
-          end
-        end
-      end
-
-      # Evaluates symbol (method reference) or proc (responds to call) options
-      # XXX:Keep
-      #
-      # If the option is not a symbol or proc then the original option is returned
-      def evaluate_attr_masker_option(option)
-        if option.is_a?(Symbol) && respond_to?(option)
-          send(option)
-        elsif option.respond_to?(:call)
-          option.call(self)
-        else
-          option
-        end
-      end
-  end
 end
 
-Object.extend AttrMasker
+Object.extend AttrMasker::Model

data/lib/attr_masker/attribute.rb

@@ -0,0 +1,80 @@
+# (c) 2017 Ribose Inc.
+#
+
+module AttrMasker
+  # Holds the definition of maskable attribute.
+  class Attribute
+    attr_reader :name, :model, :options
+
+    def initialize(name, model, options)
+      @name = name.to_sym
+      @model = model
+      @options = options
+    end
+
+    # Evaluates the +:if+ and +:unless+ attribute options on given instance.
+    # Returns +true+ or +false+, depending on whether the attribute should be
+    # masked for this object or not.
+    def should_mask?(model_instance)
+      not (
+        options.key?(:if) && !evaluate_option(:if, model_instance) ||
+        options.key?(:unless) && evaluate_option(:unless, model_instance)
+      )
+    end
+
+    # Mask the attribute on given model.  Masking will be performed regardless
+    # of +:if+ and +:unless+ options.  A +should_mask?+ method should be called
+    # separately to ensure that given object is eligible for masking.
+    #
+    # The method returns the masked value but does not modify the object's
+    # attribute.
+    #
+    # If +marshal+ attribute's option is +true+, the attribute value will be
+    # loaded before masking, and dumped to proper storage format prior
+    # returning.
+    def mask(model_instance)
+      value = unmarshal_data(model_instance.send(name))
+      masker = options[:masker]
+      masker_value = masker.call(value: value, model: model_instance,
+                                 attribute_name: name, masking_options: options)
+      model_instance.send("#{name}=", marshal_data(masker_value))
+    end
+
+    # Returns a hash of maskable attribute names, and respective attribute
+    # values.  Unchanged attributes are skipped.
+    def masked_attributes_new_values(model_instance)
+      model_instance.changes.slice(*column_names).transform_values(&:second)
+    end
+
+    # Evaluates option (typically +:if+ or +:unless+) on given model instance.
+    # That option can be either a proc (a model is passed as an only argument),
+    # or a symbol (a method of that name is called on model instance).
+    def evaluate_option(option_name, model_instance)
+      option = options[option_name]
+
+      if option.is_a?(Symbol)
+        model_instance.send(option)
+      elsif option.respond_to?(:call)
+        option.call(model_instance)
+      else
+        option
+      end
+    end
+
+    def marshal_data(data)
+      return data unless options[:marshal]
+
+      options[:marshaler].send(options[:dump_method], data)
+    end
+
+    def unmarshal_data(data)
+      return data unless options[:marshal]
+
+      options[:marshaler].send(options[:load_method], data)
+    end
+
+    def column_names
+      options[:column_names] || [name]
+    end
+  end
+end

data/lib/attr_masker/error.rb

@@ -1,5 +1,6 @@
 # (c) 2017 Ribose Inc.
 #
+
 module AttrMasker
   class Error < ::StandardError
   end

data/lib/attr_masker/maskers/replacing.rb

@@ -1,15 +1,32 @@
 # (c) 2017 Ribose Inc.
 #
+
 module AttrMasker
   module Maskers
-    # This default masker simply replaces any value with a fixed string.
+    # +Replacing+ masker replaces every character of string which is being
+    # masked with +replacement+ one, preserving the length of the masked string
+    # (provided that a replacement string contains a single character, which is
+    # a typical case). Optionally, non-alphanumeric characters like dashes or
+    # spaces may be left unchanged.
     #
-    # +opts+ is a Hash with the key :value that gives you the current attribute
-    # value.
+    # @example Would mask "Adam West" as "XXXXXXXXX"
+    #   class User < ActiveRecord::Base
+    #     m = AttrMasker::Maskers::Replacing.new(replacement: "X")
+    #     attr_masker :name, :masker => m
+    #   end
     #
+    # @example Would mask "123-456-789" as "XXX-XXX-XXX"
+    #   class User < ActiveRecord::Base
+    #     m = AttrMasker::Maskers::Replacing.new(
+    #         replacement: "X", alphanum_only: true)
+    #     attr_masker :phone, :masker => m
+    #   end
     class Replacing
       attr_reader :replacement, :alphanum_only
 
+      # @param replacement [String] replacement string
+      # @param alphanum_only [Boolean] whether to leave non-alphanumeric
+      #   characters unchanged or not
       def initialize(replacement: "*", alphanum_only: false)
         replacement = "" if replacement.nil?
         @replacement = replacement

data/lib/attr_masker/maskers/simple.rb

@@ -1,12 +1,27 @@
+# (c) 2017 Ribose Inc.
+#
+
 module AttrMasker
   module Maskers
-    # This default masker simply replaces any value with a fixed string.
+    # +Simple+ masker replaces values with a predefined +(redacted)+ string.
+    # This is a default masker, which is used when no specific +:masker+ is
+    # passed in +attr_masker+ method call.
     #
-    # +opts+ is a Hash with the key :value that gives you the current attribute
-    # value.
+    # @example Would mask "Adam West" as "(redacted)"
+    #   class User < ActiveRecord::Base
+    #     m = AttrMasker::Maskers::Simple.new
+    #     attr_masker :name, :masker => m
+    #   end
     #
-    SIMPLE = lambda do |_opts|
-      "(redacted)"
+    # @example Would mask "Adam West" as "(redacted)"
+    #   class User < ActiveRecord::Base
+    #     attr_masker :name
+    #   end
+    class Simple
+      # Accepts any keyword arguments, but they all are ignored.
+      def call(**_opts)
+        "(redacted)"
+      end
     end
   end
 end

data/lib/attr_masker/model.rb

@@ -0,0 +1,143 @@
+# (c) 2017 Ribose Inc.
+#
+
+module AttrMasker
+  module Model
+    def self.extended(base) # :nodoc:
+      base.class_eval do
+        attr_writer :attr_masker_options
+        @attr_masker_options = {}
+        @masker_attributes = {}
+      end
+    end
+
+    # Generates attr_accessors that mask attributes transparently
+    #
+    # Options (any other options you specify are passed to the masker's mask
+    # methods)
+    #
+    # [:masker]
+    #     The object to use for masking. It must respond to +#mask+. Defaults to
+    #     AttrMasker::Maskers::Simple.
+    #
+    # [:if]
+    #     Attributes are only masker if this option evaluates to true. If you
+    #     pass a symbol representing an instance method then the result of
+    #     the method will be evaluated. Any objects that respond to
+    #     <tt>:call</tt> are evaluated as well.  Defaults to true.
+    #
+    # [:unless]
+    #     Attributes are only masker if this option evaluates to false. If you
+    #     pass a symbol representing an instance method then the result of
+    #     the method will be evaluated. Any objects that respond to
+    #     <tt>:call</tt> are evaluated as well.  Defaults to false.
+    #
+    # [:marshal]
+    #     If set to true, attributes will be marshaled as well as masker. This
+    #     is useful if you're planning on masking something other than a string.
+    #     Defaults to false unless you're using it with ActiveRecord or
+    #     DataMapper.
+    #
+    # [:marshaler]
+    #     The object to use for marshaling. Defaults to Marshal.
+    #
+    # [:dump_method]
+    #     The dump method name to call on the <tt>:marshaler</tt> object to.
+    #     Defaults to 'dump'.
+    #
+    # [:load_method]
+    #     The load method name to call on the <tt>:marshaler</tt> object.
+    #     Defaults to 'load'.
+    #
+    # You can specify your own default options
+    #
+    #   class User
+    #     # now all attributes will be encoded and marshaled by default
+    #     attr_masker_options.merge!(:marshal => true, :another_option => true)
+    #     attr_masker :configuration
+    #   end
+    #
+    #
+    # Example
+    #
+    #   class User
+    #     attr_masker :email, :credit_card
+    #     attr_masker :configuration, :marshal => true
+    #   end
+    #
+    #   @user = User.new
+    #   @user.masker_email # nil
+    #   @user.email? # false
+    #   @user.email = 'test@example.com'
+    #   @user.email? # true
+    #   @user.masker_email # returns the masker version of 'test@example.com'
+    #
+    #   @user.configuration = { :time_zone => 'UTC' }
+    #   @user.masker_configuration # returns the masker version of configuration
+    #
+    #   See README for more examples
+    #--
+    # rubocop:disable Metrics/MethodLength
+    def attr_masker(*args)
+      default_options = {
+        if: true,
+        unless: false,
+        column_name: nil,
+        marshal: false,
+        marshaler: Marshal,
+        dump_method: "dump",
+        load_method: "load",
+        masker: AttrMasker::Maskers::Simple.new,
+      }
+
+      options = args.extract_options!.
+        reverse_merge(attr_masker_options).
+        reverse_merge(default_options)
+
+      args.each do |attribute_name|
+        attribute = Attribute.new(attribute_name, self, options)
+        masker_attributes[attribute.name] = attribute
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    # Default options to use with calls to <tt>attr_masker</tt>
+    # XXX:Keep
+    #
+    # It will inherit existing options from its superclass
+    def attr_masker_options
+      @attr_masker_options ||= superclass.attr_masker_options.dup
+    end
+
+    # Checks if an attribute is configured with <tt>attr_masker</tt>
+    # XXX:Keep
+    #
+    # Example
+    #
+    #   class User
+    #     attr_accessor :name
+    #     attr_masker :email
+    #   end
+    #
+    #   User.attr_masker?(:name)  # false
+    #   User.attr_masker?(:email) # true
+    def attr_masker?(attribute)
+      masker_attributes.has_key?(attribute.to_sym)
+    end
+
+    # Contains a hash of masker attributes with virtual attribute names as keys
+    # and their corresponding options as values
+    # XXX:Keep
+    #
+    # Example
+    #
+    #   class User
+    #     attr_masker :email
+    #   end
+    #
+    #   User.masker_attributes # { :email => { :attribute => 'masker_email' } }
+    def masker_attributes
+      @masker_attributes ||= superclass.masker_attributes.dup
+    end
+  end
+end