activemodel 3.0.pre → 3.0.0.rc

data/lib/active_model/lint.rb

@@ -1,5 +1,7 @@
-# You can test whether an object is compliant with the ActiveModel API by
-# including ActiveModel::Lint::Tests in your TestCase. It will included
+# == Active Model Lint Tests
+#
+# You can test whether an object is compliant with the Active Model API by
+# including <tt>ActiveModel::Lint::Tests</tt> in your TestCase. It will include
 # tests that tell you whether your object is fully compliant, or if not,
 # which aspects of the API are not implemented.
 #
@@ -13,8 +15,34 @@
 module ActiveModel
   module Lint
     module Tests
-      # valid?
-      # ------
+
+      # == Responds to <tt>to_key</tt>
+      #
+      # Returns an Enumerable of all (primary) key attributes
+      # or nil if model.persisted? is false
+      def test_to_key
+        assert model.respond_to?(:to_key), "The model should respond to to_key"
+        def model.persisted?() false end
+        assert model.to_key.nil?
+      end
+
+      # == Responds to <tt>to_param</tt>
+      #
+      # Returns a string representing the object's key suitable for use in URLs
+      # or nil if model.persisted? is false.
+      #
+      # Implementers can decide to either raise an exception or provide a default
+      # in case the record uses a composite primary key. There are no tests for this
+      # behavior in lint because it doesn't make sense to force any of the possible
+      # implementation strategies on the implementer. However, if the resource is
+      # not persisted?, then to_param should always return nil.
+      def test_to_param
+        assert model.respond_to?(:to_param), "The model should respond to to_param"
+        def model.persisted?() false end
+        assert model.to_param.nil?
+      end
+
+      # == Responds to <tt>valid?</tt>
       #
       # Returns a boolean that specifies whether the object is in a valid or invalid
       # state.
@@ -23,30 +51,38 @@ module ActiveModel
         assert_boolean model.valid?, "valid?"
       end
 
-      # new_record?
-      # -----------
+      # == Responds to <tt>persisted?</tt>
       #
       # Returns a boolean that specifies whether the object has been persisted yet.
       # This is used when calculating the URL for an object. If the object is
       # not persisted, a form for that object, for instance, will be POSTed to the
-      # collection. If it is persisted, a form for the object will put PUTed to the
+      # collection. If it is persisted, a form for the object will be PUT to the
       # URL for the object.
-      def test_new_record?
-        assert model.respond_to?(:new_record?), "The model should respond to new_record?"
-        assert_boolean model.new_record?, "new_record?"
+      def test_persisted?
+        assert model.respond_to?(:persisted?), "The model should respond to persisted?"
+        assert_boolean model.persisted?, "persisted?"
       end
 
-      def test_destroyed?
-        assert model.respond_to?(:destroyed?), "The model should respond to destroyed?"
-        assert_boolean model.destroyed?, "destroyed?"
+      # == Naming
+      #
+      # Model.model_name must return a string with some convenience methods as
+      # :human and :partial_path. Check ActiveModel::Naming for more information.
+      #
+      def test_model_naming
+        assert model.class.respond_to?(:model_name), "The model should respond to model_name"
+        model_name = model.class.model_name
+        assert_kind_of String, model_name
+        assert_kind_of String, model_name.human
+        assert_kind_of String, model_name.partial_path
+        assert_kind_of String, model_name.singular
+        assert_kind_of String, model_name.plural
       end
 
-      # errors
-      # ------
-      #
+      # == Errors Testing
+      # 
       # Returns an object that has :[] and :full_messages defined on it. See below
       # for more details.
-
+      #
       # Returns an Array of Strings that are the errors for the attribute in
       # question. If localization is used, the Strings should be localized
       # for the current locale. If no error is present, this method should

data/lib/active_model/locale/en.yml

@@ -1,24 +1,27 @@
 en:
-  activemodel:
-    errors:
-      # The values :model, :attribute and :value are always available for interpolation
-      # The value :count is available when applicable. Can be used for pluralization.
-      messages:
-        inclusion: "is not included in the list"
-        exclusion: "is reserved"
-        invalid: "is invalid"
-        confirmation: "doesn't match confirmation"
-        accepted: "must be accepted"
-        empty: "can't be empty"
-        blank: "can't be blank"
-        too_long: "is too long (maximum is {{count}} characters)"
-        too_short: "is too short (minimum is {{count}} characters)"
-        wrong_length: "is the wrong length (should be {{count}} characters)"
-        not_a_number: "is not a number"
-        greater_than: "must be greater than {{count}}"
-        greater_than_or_equal_to: "must be greater than or equal to {{count}}"
-        equal_to: "must be equal to {{count}}"
-        less_than: "must be less than {{count}}"
-        less_than_or_equal_to: "must be less than or equal to {{count}}"
-        odd: "must be odd"
-        even: "must be even"
+  errors:
+    # The default format to use in full error messages.
+    format: "%{attribute} %{message}"
+
+    # The values :model, :attribute and :value are always available for interpolation
+    # The value :count is available when applicable. Can be used for pluralization.
+    messages:
+      inclusion: "is not included in the list"
+      exclusion: "is reserved"
+      invalid: "is invalid"
+      confirmation: "doesn't match confirmation"
+      accepted: "must be accepted"
+      empty: "can't be empty"
+      blank: "can't be blank"
+      too_long: "is too long (maximum is %{count} characters)"
+      too_short: "is too short (minimum is %{count} characters)"
+      wrong_length: "is the wrong length (should be %{count} characters)"
+      not_a_number: "is not a number"
+      not_an_integer: "must be an integer"
+      greater_than: "must be greater than %{count}"
+      greater_than_or_equal_to: "must be greater than or equal to %{count}"
+      equal_to: "must be equal to %{count}"
+      less_than: "must be less than %{count}"
+      less_than_or_equal_to: "must be less than or equal to %{count}"
+      odd: "must be odd"
+      even: "must be even"

data/lib/active_model/mass_assignment_security.rb

@@ -0,0 +1,160 @@
+require 'active_support/core_ext/class/attribute.rb'
+require 'active_model/mass_assignment_security/permission_set'
+
+module ActiveModel
+  # = Active Model Mass-Assignment Security
+  module MassAssignmentSecurity
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_accessible_attributes
+      class_attribute :_protected_attributes
+      class_attribute :_active_authorizer
+    end
+
+    # Mass assignment security provides an interface for protecting attributes
+    # from end-user assignment. For more complex permissions, mass assignment security
+    # may be handled outside the model by extending a non-ActiveRecord class,
+    # such as a controller, with this behavior.
+    #
+    # For example, a logged in user may need to assign additional attributes depending
+    # on their role:
+    #
+    # class AccountsController < ApplicationController
+    #   include ActiveModel::MassAssignmentSecurity
+    #
+    #   attr_accessible :first_name, :last_name
+    #
+    #   def self.admin_accessible_attributes
+    #     accessible_attributes + [ :plan_id ]
+    #   end
+    #
+    #   def update
+    #     ...
+    #     @account.update_attributes(account_params)
+    #     ...
+    #   end
+    #
+    #   protected
+    #
+    #   def account_params
+    #     sanitize_for_mass_assignment(params[:account])
+    #   end
+    #
+    #   def mass_assignment_authorizer
+    #     admin ? admin_accessible_attributes : super
+    #   end
+    #
+    # end
+    #
+    module ClassMethods
+      # Attributes named in this macro are protected from mass-assignment
+      # whenever attributes are sanitized before assignment.
+      #
+      # Mass-assignment to these attributes will simply be ignored, to assign
+      # to them you can use direct writer methods. This is meant to protect
+      # sensitive attributes from being overwritten by malicious users
+      # tampering with URLs or forms.
+      #
+      # == Example
+      #
+      #   class Customer
+      #     include ActiveModel::MassAssignmentSecurity
+      #
+      #     attr_accessor :name, :credit_rating
+      #     attr_protected :credit_rating
+      #
+      #     def attributes=(values)
+      #       sanitize_for_mass_assignment(values).each do |k, v|
+      #         send("#{k}=", v)
+      #       end
+      #     end
+      #   end
+      #
+      #   customer = Customer.new
+      #   customer.attributes = { "name" => "David", "credit_rating" => "Excellent" }
+      #   customer.name          # => "David"
+      #   customer.credit_rating # => nil
+      #
+      #   customer.credit_rating = "Average"
+      #   customer.credit_rating # => "Average"
+      #
+      # To start from an all-closed default and enable attributes as needed,
+      # have a look at +attr_accessible+.
+      #
+      # Note that using <tt>Hash#except</tt> or <tt>Hash#slice</tt> in place of +attr_protected+
+      # to sanitize attributes won't provide sufficient protection.
+      def attr_protected(*names)
+        self._protected_attributes = self.protected_attributes + names
+        self._active_authorizer = self._protected_attributes
+      end
+
+      # Specifies a white list of model attributes that can be set via
+      # mass-assignment.
+      #
+      # This is the opposite of the +attr_protected+ macro: Mass-assignment
+      # will only set attributes in this list, to assign to the rest of
+      # attributes you can use direct writer methods. This is meant to protect
+      # sensitive attributes from being overwritten by malicious users
+      # tampering with URLs or forms. If you'd rather start from an all-open
+      # default and restrict attributes as needed, have a look at
+      # +attr_protected+.
+      #
+      #   class Customer
+      #     include ActiveModel::MassAssignmentSecurity
+      #
+      #     attr_accessor :name, :credit_rating
+      #     attr_accessible :name
+      #
+      #     def attributes=(values)
+      #       sanitize_for_mass_assignment(values).each do |k, v|
+      #         send("#{k}=", v)
+      #       end
+      #     end
+      #   end
+      #
+      #   customer = Customer.new
+      #   customer.attributes = { :name => "David", :credit_rating => "Excellent" }
+      #   customer.name          # => "David"
+      #   customer.credit_rating # => nil
+      #
+      #   customer.credit_rating = "Average"
+      #   customer.credit_rating # => "Average"
+      #
+      # Note that using <tt>Hash#except</tt> or <tt>Hash#slice</tt> in place of +attr_accessible+
+      # to sanitize attributes won't provide sufficient protection.
+      def attr_accessible(*names)
+        self._accessible_attributes = self.accessible_attributes + names
+        self._active_authorizer = self._accessible_attributes
+      end
+
+      def protected_attributes
+        self._protected_attributes ||= BlackList.new(attributes_protected_by_default).tap do |w|
+          w.logger = self.logger if self.respond_to?(:logger)
+        end
+      end
+
+      def accessible_attributes
+        self._accessible_attributes ||= WhiteList.new.tap { |w| w.logger = self.logger if self.respond_to?(:logger) }
+      end
+
+      def active_authorizer
+        self._active_authorizer ||= protected_attributes
+      end
+
+      def attributes_protected_by_default
+        []
+      end
+    end
+
+  protected
+
+    def sanitize_for_mass_assignment(attributes)
+      mass_assignment_authorizer.sanitize(attributes)
+    end
+
+    def mass_assignment_authorizer
+      self.class.active_authorizer
+    end
+  end
+end

data/lib/active_model/mass_assignment_security/permission_set.rb

@@ -0,0 +1,40 @@
+require 'set'
+require 'active_model/mass_assignment_security/sanitizer'
+
+module ActiveModel
+  module MassAssignmentSecurity
+    class PermissionSet < Set
+      attr_accessor :logger
+
+      def +(values)
+        super(values.map(&:to_s))
+      end
+
+      def include?(key)
+        super(remove_multiparameter_id(key))
+      end
+
+    protected
+
+      def remove_multiparameter_id(key)
+        key.to_s.gsub(/\(.+/, '')
+      end
+    end
+
+    class WhiteList < PermissionSet
+      include Sanitizer
+
+      def deny?(key)
+        !include?(key)
+      end
+    end
+
+    class BlackList < PermissionSet
+      include Sanitizer
+
+      def deny?(key)
+        include?(key)
+      end
+    end
+  end
+end

data/lib/active_model/mass_assignment_security/sanitizer.rb

@@ -0,0 +1,23 @@
+module ActiveModel
+  module MassAssignmentSecurity
+    module Sanitizer
+      # Returns all attributes not denied by the authorizer.
+      def sanitize(attributes)
+        sanitized_attributes = attributes.reject { |key, value| deny?(key) }
+        debug_protected_attribute_removal(attributes, sanitized_attributes)
+        sanitized_attributes
+      end
+
+    protected
+
+      def debug_protected_attribute_removal(attributes, sanitized_attributes)
+        removed_keys = attributes.keys - sanitized_attributes.keys
+        warn!(removed_keys) if removed_keys.any?
+      end
+
+      def warn!(attrs)
+        self.logger.debug "WARNING: Can't mass-assign protected attributes: #{attrs.join(', ')}" if self.logger
+      end
+    end
+  end
+end

data/lib/active_model/naming.rb

@@ -2,25 +2,90 @@ require 'active_support/inflector'
 
 module ActiveModel
   class Name < String
-    attr_reader :singular, :plural, :element, :collection, :partial_path, :human
+    attr_reader :singular, :plural, :element, :collection, :partial_path
     alias_method :cache_key, :collection
 
-    def initialize(name)
-      super
+    def initialize(klass)
+      super(klass.name)
+      @klass = klass
       @singular = ActiveSupport::Inflector.underscore(self).tr('/', '_').freeze
       @plural = ActiveSupport::Inflector.pluralize(@singular).freeze
       @element = ActiveSupport::Inflector.underscore(ActiveSupport::Inflector.demodulize(self)).freeze
-      @human = @element.gsub(/_/, " ")
+      @human = ActiveSupport::Inflector.humanize(@element).freeze
       @collection = ActiveSupport::Inflector.tableize(self).freeze
       @partial_path = "#{@collection}/#{@element}".freeze
     end
+
+    # Transform the model name into a more humane format, using I18n. By default,
+    # it will underscore then humanize the class name (BlogPost.model_name.human #=> "Blog post").
+    # Specify +options+ with additional translating options.
+    def human(options={})
+      return @human unless @klass.respond_to?(:lookup_ancestors) &&
+                           @klass.respond_to?(:i18n_scope)
+
+      defaults = @klass.lookup_ancestors.map do |klass|
+        klass.model_name.underscore.to_sym
+      end
+
+      defaults << options.delete(:default) if options[:default]
+      defaults << @human
+
+      options.reverse_merge! :scope => [@klass.i18n_scope, :models], :count => 1, :default => defaults
+      I18n.translate(defaults.shift, options)
+    end
   end
 
+  # == Active Model Naming
+  #
+  # Creates a +model_name+ method on your object.
+  # 
+  # To implement, just extend ActiveModel::Naming in your object:
+  # 
+  #   class BookCover
+  #     extend ActiveModel::Naming
+  #   end
+  # 
+  #   BookCover.model_name        #=> "BookCover"
+  #   BookCover.model_name.human  #=> "Book cover"
+  # 
+  # Providing the functionality that ActiveModel::Naming provides in your object
+  # is required to pass the Active Model Lint test.  So either extending the provided
+  # method below, or rolling your own is required..
   module Naming
     # Returns an ActiveModel::Name object for module. It can be
     # used to retrieve all kinds of naming-related information.
     def model_name
-      @_model_name ||= ActiveModel::Name.new(name)
+      @_model_name ||= ActiveModel::Name.new(self)
+    end
+
+    # Returns the plural class name of a record or class. Examples:
+    #
+    #   ActiveModel::Naming.plural(post)             # => "posts"
+    #   ActiveModel::Naming.plural(Highrise::Person) # => "highrise_people"
+    def self.plural(record_or_class)
+      model_name_from_record_or_class(record_or_class).plural
+    end
+
+    # Returns the singular class name of a record or class. Examples:
+    #
+    #   ActiveModel::Naming.singular(post)             # => "post"
+    #   ActiveModel::Naming.singular(Highrise::Person) # => "highrise_person"
+    def self.singular(record_or_class)
+      model_name_from_record_or_class(record_or_class).singular
     end
+
+    # Identifies whether the class name of a record or class is uncountable. Examples:
+    #
+    #   ActiveModel::Naming.uncountable?(Sheep) # => true
+    #   ActiveModel::Naming.uncountable?(Post) => false
+    def self.uncountable?(record_or_class)
+      plural(record_or_class) == singular(record_or_class)
+    end
+
+    private
+      def self.model_name_from_record_or_class(record_or_class)
+        (record_or_class.is_a?(Class) ? record_or_class : record_or_class.class).model_name
+      end
   end
+  
 end