actionpack 7.0.5 → 7.1.3.4

data/lib/action_controller/metal/strong_parameters.rb

@@ -4,6 +4,7 @@ require "active_support/core_ext/hash/indifferent_access"
 require "active_support/core_ext/array/wrap"
 require "active_support/core_ext/string/filters"
 require "active_support/core_ext/object/to_query"
+require "active_support/deep_mergeable"
 require "action_dispatch/http/upload"
 require "rack/test"
 require "stringio"
@@ -64,7 +65,14 @@ module ActionController
     end
   end
 
-  # == Action Controller \Parameters
+  # Raised when initializing Parameters with keys that aren't strings or symbols.
+  #
+  #   ActionController::Parameters.new(123 => 456)
+  #   # => ActionController::InvalidParameterKey: all keys must be Strings or Symbols, got: Integer
+  class InvalidParameterKey < ArgumentError
+  end
+
+  # = Action Controller \Parameters
   #
   # Allows you to choose which attributes should be permitted for mass updating
   # and thus prevent accidentally exposing that which shouldn't be exposed.
@@ -92,12 +100,12 @@ module ActionController
   # * +permit_all_parameters+ - If it's +true+, all the parameters will be
   #   permitted by default. The default is +false+.
   # * +action_on_unpermitted_parameters+ - Controls behavior when parameters that are not explicitly
-  #    permitted are found. The default value is <tt>:log</tt> in test and development environments,
-  #    +false+ otherwise. The values can be:
+  #   permitted are found. The default value is <tt>:log</tt> in test and development environments,
+  #   +false+ otherwise. The values can be:
   #   * +false+ to take no action.
   #   * <tt>:log</tt> to emit an <tt>ActiveSupport::Notifications.instrument</tt> event on the
   #     <tt>unpermitted_parameters.action_controller</tt> topic and log at the DEBUG level.
-  #   * <tt>:raise</tt> to raise a <tt>ActionController::UnpermittedParameters</tt> exception.
+  #   * <tt>:raise</tt> to raise an ActionController::UnpermittedParameters exception.
   #
   # Examples:
   #
@@ -123,79 +131,82 @@ module ActionController
   # environment they should only be set once at boot-time and never mutated at
   # runtime.
   #
-  # You can fetch values of <tt>ActionController::Parameters</tt> using either
+  # You can fetch values of +ActionController::Parameters+ using either
   # <tt>:key</tt> or <tt>"key"</tt>.
   #
   #   params = ActionController::Parameters.new(key: "value")
   #   params[:key]  # => "value"
   #   params["key"] # => "value"
   class Parameters
+    include ActiveSupport::DeepMergeable
+
     cattr_accessor :permit_all_parameters, instance_accessor: false, default: false
 
     cattr_accessor :action_on_unpermitted_parameters, instance_accessor: false
 
     ##
-    # :method: as_json
+    # :method: deep_merge
     #
     # :call-seq:
-    #   as_json(options=nil)
+    #   deep_merge(other_hash, &block)
     #
-    # Returns a hash that can be used as the JSON representation for the parameters.
-
-    ##
-    # :method: each_key
+    # Returns a new +ActionController::Parameters+ instance with +self+ and +other_hash+ merged recursively.
     #
-    # :call-seq:
-    #   each_key()
+    # Like with <tt>Hash#merge</tt> in the standard library, a block can be provided
+    # to merge values.
     #
-    # Calls block once for each key in the parameters, passing the key.
-    # If no block is given, an enumerator is returned instead.
+    #--
+    # Implemented by ActiveSupport::DeepMergeable#deep_merge.
 
     ##
-    # :method: empty?
+    # :method: deep_merge!
     #
     # :call-seq:
-    #   empty?()
+    #   deep_merge!(other_hash, &block)
     #
-    # Returns true if the parameters have no key/value pairs.
+    # Same as +#deep_merge+, but modifies +self+.
+    #
+    #--
+    # Implemented by ActiveSupport::DeepMergeable#deep_merge!.
 
     ##
-    # :method: has_key?
+    # :method: as_json
     #
     # :call-seq:
-    #   has_key?(key)
+    #   as_json(options=nil)
     #
-    # Returns true if the given key is present in the parameters.
+    # Returns a hash that can be used as the JSON representation for the parameters.
 
     ##
-    # :method: has_value?
+    # :method: each_key
     #
     # :call-seq:
-    #   has_value?(value)
+    #   each_key(&block)
     #
-    # Returns true if the given value is present for some key in the parameters.
+    # Calls block once for each key in the parameters, passing the key.
+    # If no block is given, an enumerator is returned instead.
 
     ##
-    # :method: include?
+    # :method: empty?
     #
     # :call-seq:
-    #   include?(key)
+    #   empty?()
     #
-    # Returns true if the given key is present in the parameters.
+    # Returns true if the parameters have no key/value pairs.
 
     ##
-    # :method: key?
+    # :method: exclude?
     #
     # :call-seq:
-    #   key?(key)
+    #   exclude?(key)
     #
-    # Returns true if the given key is present in the parameters.
+    # Returns true if the given key is not present in the parameters.
 
     ##
-    # :method: member?
+    # :method: include?
     #
     # :call-seq:
-    #   member?(key)
+    #   include?(key)
     #
     # Returns true if the given key is present in the parameters.
 
@@ -215,24 +226,13 @@ module ActionController
     #
     # Returns the content of the parameters as a string.
 
-    ##
-    # :method: value?
-    #
-    # :call-seq:
-    #   value?(value)
-    #
-    # Returns true if the given value is present for some key in the parameters.
-
-    ##
-    # :method: values
-    #
-    # :call-seq:
-    #   values()
-    #
-    # Returns a new array of the values of the parameters.
-    delegate :keys, :key?, :has_key?, :member?, :values, :has_value?, :value?, :empty?, :include?,
+    delegate :keys, :empty?, :exclude?, :include?,
       :as_json, :to_s, :each_key, to: :@parameters
 
+    alias_method :has_key?, :include?
+    alias_method :key?, :include?
+    alias_method :member?, :include?
+
     # By default, never raise an UnpermittedParameters exception if these
     # params are present. The default includes both 'controller' and 'action'
     # because they are added by Rails and should be of no concern. One way
@@ -242,13 +242,15 @@ module ActionController
     #    config.action_controller.always_permitted_parameters = %w( controller action format )
     cattr_accessor :always_permitted_parameters, default: %w( controller action )
 
+    cattr_accessor :allow_deprecated_parameters_hash_equality, default: true, instance_accessor: false
+
     class << self
       def nested_attribute?(key, value) # :nodoc:
         /\A-?\d+\z/.match?(key) && (value.is_a?(Hash) || value.is_a?(Parameters))
       end
     end
 
-    # Returns a new instance of <tt>ActionController::Parameters</tt>.
+    # Returns a new +ActionController::Parameters+ instance.
     # Also, sets the +permitted+ attribute to the default value of
     # <tt>ActionController::Parameters.permit_all_parameters</tt>.
     #
@@ -265,6 +267,12 @@ module ActionController
     #   params.permitted?  # => true
     #   Person.new(params) # => #<Person id: nil, name: "Francesco">
     def initialize(parameters = {}, logging_context = {})
+      parameters.each_key do |key|
+        unless key.is_a?(String) || key.is_a?(Symbol)
+          raise InvalidParameterKey, "all keys must be Strings or Symbols, got: #{key.class}"
+        end
+      end
+
       @parameters = parameters.with_indifferent_access
       @logging_context = logging_context
       @permitted = self.class.permit_all_parameters
@@ -276,7 +284,20 @@ module ActionController
       if other.respond_to?(:permitted?)
         permitted? == other.permitted? && parameters == other.parameters
       else
-        @parameters == other
+        if self.class.allow_deprecated_parameters_hash_equality && Hash === other
+          ActionController.deprecator.warn <<-WARNING.squish
+            Comparing equality between `ActionController::Parameters` and a
+            `Hash` is deprecated and will be removed in Rails 7.2. Please only do
+            comparisons between instances of `ActionController::Parameters`. If
+            you need to compare to a hash, first convert it using
+            `ActionController::Parameters#new`.
+            To disable the deprecated behavior set
+            `Rails.application.config.action_controller.allow_deprecated_parameters_hash_equality = false`.
+          WARNING
+          @parameters == other
+        else
+          super
+        end
       end
     end
 
@@ -290,7 +311,7 @@ module ActionController
       [self.class, @parameters, @permitted].hash
     end
 
-    # Returns a safe <tt>ActiveSupport::HashWithIndifferentAccess</tt>
+    # Returns a safe ActiveSupport::HashWithIndifferentAccess
     # representation of the parameters with all unpermitted keys removed.
     #
     #   params = ActionController::Parameters.new({
@@ -302,9 +323,9 @@ module ActionController
     #
     #   safe_params = params.permit(:name)
     #   safe_params.to_h # => {"name"=>"Senjougahara Hitagi"}
-    def to_h
+    def to_h(&block)
       if permitted?
-        convert_parameters_to_hashes(@parameters, :to_h)
+        convert_parameters_to_hashes(@parameters, :to_h, &block)
       else
         raise UnfilteredParameters
       end
@@ -350,18 +371,15 @@ module ActionController
     #   safe_params.to_query("user")
     #   # => "user%5Bname%5D=David&user%5Bnationality%5D=Danish"
     #
-    # The string pairs "key=value" that conform the query string
+    # The string pairs <tt>"key=value"</tt> that conform the query string
     # are sorted lexicographically in ascending order.
-    #
-    # This method is also aliased as +to_param+.
     def to_query(*args)
       to_h.to_query(*args)
     end
     alias_method :to_param, :to_query
 
-    # Returns an unsafe, unfiltered
-    # <tt>ActiveSupport::HashWithIndifferentAccess</tt> representation of the
-    # parameters.
+    # Returns an unsafe, unfiltered ActiveSupport::HashWithIndifferentAccess
+    # representation of the parameters.
     #
     #   params = ActionController::Parameters.new({
     #     name: "Senjougahara Hitagi",
@@ -397,11 +415,16 @@ module ActionController
       self
     end
 
+    # Returns a new array of the values of the parameters.
+    def values
+      to_enum(:each_value).to_a
+    end
+
     # Attribute that keeps track of converted arrays, if any, to avoid double
     # looping in the common use case permit + mass-assignment. Defined in a
     # method to instantiate it only if needed.
     #
-    # Testing membership still loops, but it's going to be faster than our own
+    # \Testing membership still loops, but it's going to be faster than our own
     # loop that converts values. Also, we are not going to build a new array
     # object per fetch.
     def converted_arrays
@@ -449,7 +472,7 @@ module ActionController
     #   ActionController::Parameters.new(person: { name: "Francesco" }).require(:person)
     #   # => #<ActionController::Parameters {"name"=>"Francesco"} permitted: false>
     #
-    # Otherwise raises <tt>ActionController::ParameterMissing</tt>:
+    # Otherwise raises ActionController::ParameterMissing:
     #
     #   ActionController::Parameters.new.require(:person)
     #   # ActionController::ParameterMissing: param is missing or the value is empty: person
@@ -501,10 +524,9 @@ module ActionController
       end
     end
 
-    # Alias of #require.
     alias :required :require
 
-    # Returns a new <tt>ActionController::Parameters</tt> instance that
+    # Returns a new +ActionController::Parameters+ instance that
     # includes only the given +filters+ and sets the +permitted+ attribute
     # for the object to +true+. This is useful for limiting which attributes
     # should be allowed for mass updating.
@@ -523,7 +545,7 @@ module ActionController
     # +:name+ passes if it is a key of +params+ whose associated value is of type
     # +String+, +Symbol+, +NilClass+, +Numeric+, +TrueClass+, +FalseClass+,
     # +Date+, +Time+, +DateTime+, +StringIO+, +IO+,
-    # +ActionDispatch::Http::UploadedFile+ or +Rack::Test::UploadedFile+.
+    # ActionDispatch::Http::UploadedFile or +Rack::Test::UploadedFile+.
     # Otherwise, the key +:name+ is filtered out.
     #
     # You may declare that the parameter should be an array of permitted scalars
@@ -645,16 +667,16 @@ module ActionController
     end
 
     # Assigns a value to a given +key+. The given key may still get filtered out
-    # when +permit+ is called.
+    # when #permit is called.
     def []=(key, value)
       @parameters[key] = value
     end
 
     # Returns a parameter for the given +key+. If the +key+
     # can't be found, there are several options: With no other arguments,
-    # it will raise an <tt>ActionController::ParameterMissing</tt> error;
+    # it will raise an ActionController::ParameterMissing error;
     # if a second argument is given, then that is returned (converted to an
-    # instance of ActionController::Parameters if possible); if a block
+    # instance of +ActionController::Parameters+ if possible); if a block
     # is given, then that will be run and its result returned.
     #
     #   params = ActionController::Parameters.new(person: { name: "Francesco" })
@@ -689,7 +711,7 @@ module ActionController
       @parameters.dig(*keys)
     end
 
-    # Returns a new <tt>ActionController::Parameters</tt> instance that
+    # Returns a new +ActionController::Parameters+ instance that
     # includes only the given +keys+. If the given +keys+
     # don't exist, returns an empty hash.
     #
@@ -700,14 +722,14 @@ module ActionController
       new_instance_with_inherited_permitted_status(@parameters.slice(*keys))
     end
 
-    # Returns current <tt>ActionController::Parameters</tt> instance which
+    # Returns the current +ActionController::Parameters+ instance which
     # contains only the given +keys+.
     def slice!(*keys)
       @parameters.slice!(*keys)
       self
     end
 
-    # Returns a new <tt>ActionController::Parameters</tt> instance that
+    # Returns a new +ActionController::Parameters+ instance that
     # filters out the given +keys+.
     #
     #   params = ActionController::Parameters.new(a: 1, b: 2, c: 3)
@@ -716,6 +738,7 @@ module ActionController
     def except(*keys)
       new_instance_with_inherited_permitted_status(@parameters.except(*keys))
     end
+    alias_method :without, :except
 
     # Removes and returns the key/value pairs matching the given keys.
     #
@@ -726,7 +749,7 @@ module ActionController
       new_instance_with_inherited_permitted_status(@parameters.extract!(*keys))
     end
 
-    # Returns a new <tt>ActionController::Parameters</tt> with the results of
+    # Returns a new +ActionController::Parameters+ instance with the results of
     # running +block+ once for every value. The keys are unchanged.
     #
     #   params = ActionController::Parameters.new(a: 1, b: 2, c: 3)
@@ -740,14 +763,14 @@ module ActionController
     end
 
     # Performs values transformation and returns the altered
-    # <tt>ActionController::Parameters</tt> instance.
+    # +ActionController::Parameters+ instance.
     def transform_values!
       return to_enum(:transform_values!) unless block_given?
       @parameters.transform_values! { |v| yield convert_value_to_parameters(v) }
       self
     end
 
-    # Returns a new <tt>ActionController::Parameters</tt> instance with the
+    # Returns a new +ActionController::Parameters+ instance with the
     # results of running +block+ once for every key. The values are unchanged.
     def transform_keys(&block)
       return to_enum(:transform_keys) unless block_given?
@@ -757,14 +780,14 @@ module ActionController
     end
 
     # Performs keys transformation and returns the altered
-    # <tt>ActionController::Parameters</tt> instance.
+    # +ActionController::Parameters+ instance.
     def transform_keys!(&block)
       return to_enum(:transform_keys!) unless block_given?
       @parameters.transform_keys!(&block)
       self
     end
 
-    # Returns a new <tt>ActionController::Parameters</tt> instance with the
+    # Returns a new +ActionController::Parameters+ instance with the
     # results of running +block+ once for every key. This includes the keys
     # from the root hash and from all nested hashes and arrays. The values are unchanged.
     def deep_transform_keys(&block)
@@ -773,9 +796,9 @@ module ActionController
       )
     end
 
-    # Returns the <tt>ActionController::Parameters</tt> instance changing its keys.
-    # This includes the keys from the root hash and from all nested hashes and arrays.
-    # The values are unchanged.
+    # Returns the same +ActionController::Parameters+ instance with
+    # changed keys. This includes the keys from the root hash and from all
+    # nested hashes and arrays. The values are unchanged.
     def deep_transform_keys!(&block)
       @parameters.deep_transform_keys!(&block)
       self
@@ -783,13 +806,13 @@ module ActionController
 
     # Deletes a key-value pair from +Parameters+ and returns the value. If
     # +key+ is not found, returns +nil+ (or, with optional code block, yields
-    # +key+ and returns the result). Cf. #extract!, which returns the
-    # corresponding +ActionController::Parameters+ object.
+    # +key+ and returns the result). This method is similar to #extract!, which
+    # returns the corresponding +ActionController::Parameters+ object.
     def delete(key, &block)
       convert_value_to_parameters(@parameters.delete(key, &block))
     end
 
-    # Returns a new instance of <tt>ActionController::Parameters</tt> with only
+    # Returns a new +ActionController::Parameters+ instance with only
     # items that the block evaluates to true.
     def select(&block)
       new_instance_with_inherited_permitted_status(@parameters.select(&block))
@@ -802,7 +825,7 @@ module ActionController
     end
     alias_method :keep_if, :select!
 
-    # Returns a new instance of <tt>ActionController::Parameters</tt> with items
+    # Returns a new +ActionController::Parameters+ instance with items
     # that the block evaluates to true removed.
     def reject(&block)
       new_instance_with_inherited_permitted_status(@parameters.reject(&block))
@@ -815,7 +838,7 @@ module ActionController
     end
     alias_method :delete_if, :reject!
 
-    # Returns a new instance of <tt>ActionController::Parameters</tt> with +nil+ values removed.
+    # Returns a new +ActionController::Parameters+ instance with +nil+ values removed.
     def compact
       new_instance_with_inherited_permitted_status(@parameters.compact)
     end
@@ -825,7 +848,7 @@ module ActionController
       self if @parameters.compact!
     end
 
-    # Returns a new instance of <tt>ActionController::Parameters</tt> without the blank values.
+    # Returns a new +ActionController::Parameters+ instance without the blank values.
     # Uses Object#blank? for determining if a value is blank.
     def compact_blank
       reject { |_k, v| v.blank? }
@@ -837,13 +860,20 @@ module ActionController
       reject! { |_k, v| v.blank? }
     end
 
+    # Returns true if the given value is present for some key in the parameters.
+    def has_value?(value)
+      each_value.include?(convert_value_to_parameters(value))
+    end
+
+    alias value? has_value?
+
     # Returns values that were assigned to the given +keys+. Note that all the
-    # +Hash+ objects will be converted to <tt>ActionController::Parameters</tt>.
+    # +Hash+ objects will be converted to +ActionController::Parameters+.
     def values_at(*keys)
       convert_value_to_parameters(@parameters.values_at(*keys))
     end
 
-    # Returns a new <tt>ActionController::Parameters</tt> with all keys from
+    # Returns a new +ActionController::Parameters+ instance with all keys from
     # +other_hash+ merged into current hash.
     def merge(other_hash)
       new_instance_with_inherited_permitted_status(
@@ -851,15 +881,22 @@ module ActionController
       )
     end
 
-    # Returns current <tt>ActionController::Parameters</tt> instance with
+    ##
+    # :call-seq: merge!(other_hash)
+    #
+    # Returns the current +ActionController::Parameters+ instance with
     # +other_hash+ merged into current hash.
-    def merge!(other_hash)
-      @parameters.merge!(other_hash.to_h)
+    def merge!(other_hash, &block)
+      @parameters.merge!(other_hash.to_h, &block)
       self
     end
 
-    # Returns a new <tt>ActionController::Parameters</tt> with all keys from
-    # current hash merged into +other_hash+.
+    def deep_merge?(other_hash) # :nodoc:
+      other_hash.is_a?(ActiveSupport::DeepMergeable)
+    end
+
+    # Returns a new +ActionController::Parameters+ instance with all keys
+    # from current hash merged into +other_hash+.
     def reverse_merge(other_hash)
       new_instance_with_inherited_permitted_status(
         other_hash.to_h.merge(@parameters)
@@ -867,7 +904,7 @@ module ActionController
     end
     alias_method :with_defaults, :reverse_merge
 
-    # Returns current <tt>ActionController::Parameters</tt> instance with
+    # Returns the current +ActionController::Parameters+ instance with
     # current hash merged into +other_hash+.
     def reverse_merge!(other_hash)
       @parameters.merge!(other_hash.to_h) { |key, left, right| left }
@@ -917,13 +954,29 @@ module ActionController
       coder.map = { "parameters" => @parameters, "permitted" => @permitted }
     end
 
-    # Returns duplicate of object including all parameters.
+    # Returns a duplicate +ActionController::Parameters+ instance with the same permitted parameters.
     def deep_dup
       self.class.new(@parameters.deep_dup, @logging_context).tap do |duplicate|
         duplicate.permitted = @permitted
       end
     end
 
+    # Returns parameter value for the given +key+ separated by +delimiter+.
+    #
+    #   params = ActionController::Parameters.new(id: "1_123", tags: "ruby,rails")
+    #   params.extract_value(:id) # => ["1", "123"]
+    #   params.extract_value(:tags, delimiter: ",") # => ["ruby", "rails"]
+    #   params.extract_value(:non_existent_key) # => nil
+    #
+    # Note that if the given +key+'s value contains blank elements, then
+    # the returned array will include empty strings.
+    #
+    #   params = ActionController::Parameters.new(tags: "ruby,rails,,web")
+    #   params.extract_value(:tags) # => ["ruby", "rails", "", "web"]
+    def extract_value(key, delimiter: "_")
+      @parameters[key]&.split(delimiter, -1)
+    end
+
     protected
       attr_reader :parameters
 
@@ -946,14 +999,15 @@ module ActionController
         end
       end
 
-      def convert_parameters_to_hashes(value, using)
+      def convert_parameters_to_hashes(value, using, &block)
         case value
         when Array
           value.map { |v| convert_parameters_to_hashes(v, using) }
         when Hash
-          value.transform_values do |v|
+          transformed = value.transform_values do |v|
             convert_parameters_to_hashes(v, using)
-          end.with_indifferent_access
+          end
+          (block_given? ? transformed.to_h(&block) : transformed).with_indifferent_access
         when Parameters
           value.send(using)
         else
@@ -1024,10 +1078,11 @@ module ActionController
       # This is a list of permitted scalar types that includes the ones
       # supported in XML and JSON requests.
       #
-      # This list is in particular used to filter ordinary requests, String goes
+      # This list is in particular used to filter ordinary requests, \String goes
       # as first element to quickly short-circuit the common case.
       #
-      # If you modify this collection please update the API of +permit+ above.
+      # If you modify this collection please update the one in the #permit doc
+      # as well.
       PERMITTED_SCALAR_TYPES = [
         String,
         Symbol,
@@ -1083,8 +1138,8 @@ module ActionController
         value.is_a?(Array) || value.is_a?(Parameters)
       end
 
-      EMPTY_ARRAY = []
-      EMPTY_HASH  = {}
+      EMPTY_ARRAY = [] # :nodoc:
+      EMPTY_HASH  = {} # :nodoc:
       def hash_filter(params, filter)
         filter = filter.with_indifferent_access
 
@@ -1135,6 +1190,8 @@ module ActionController
             case element
             when ->(e) { permitted_scalar?(e) }
               sanitized << element
+            when Array
+              sanitized << permit_any_in_array(element)
             when Parameters
               sanitized << permit_any_in_parameters(element)
             else
@@ -1150,7 +1207,7 @@ module ActionController
       end
   end
 
-  # == Strong \Parameters
+  # = Strong \Parameters
   #
   # It provides an interface for protecting attributes from end-user
   # assignment. This makes Action Controller parameters forbidden

data/lib/action_controller/metal/url_for.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module ActionController
+  # = Action Controller \UrlFor
+  #
   # Includes +url_for+ into the host class. The class has to provide a +RouteSet+ by implementing
   # the <tt>_routes</tt> method. Otherwise, an exception will be raised.
   #
@@ -25,6 +27,11 @@ module ActionController
 
     include AbstractController::UrlFor
 
+    def initialize(...)
+      super
+      @_url_options = nil
+    end
+
     def url_options
       @_url_options ||= {
         host: request.host,