actionpack 5.2.3

data/lib/action_controller/metal/mime_responds.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+require "abstract_controller/collector"
+
+module ActionController #:nodoc:
+  module MimeResponds
+    # Without web-service support, an action which collects the data for displaying a list of people
+    # might look something like this:
+    #
+    #   def index
+    #     @people = Person.all
+    #   end
+    #
+    # That action implicitly responds to all formats, but formats can also be whitelisted:
+    #
+    #   def index
+    #     @people = Person.all
+    #     respond_to :html, :js
+    #   end
+    #
+    # Here's the same action, with web-service support baked in:
+    #
+    #   def index
+    #     @people = Person.all
+    #
+    #     respond_to do |format|
+    #       format.html
+    #       format.js
+    #       format.xml { render xml: @people }
+    #     end
+    #   end
+    #
+    # What that says is, "if the client wants HTML or JS in response to this action, just respond as we
+    # would have before, but if the client wants XML, return them the list of people in XML format."
+    # (Rails determines the desired response format from the HTTP Accept header submitted by the client.)
+    #
+    # Supposing you have an action that adds a new person, optionally creating their company
+    # (by name) if it does not already exist, without web-services, it might look like this:
+    #
+    #   def create
+    #     @company = Company.find_or_create_by(name: params[:company][:name])
+    #     @person  = @company.people.create(params[:person])
+    #
+    #     redirect_to(person_list_url)
+    #   end
+    #
+    # Here's the same action, with web-service support baked in:
+    #
+    #   def create
+    #     company  = params[:person].delete(:company)
+    #     @company = Company.find_or_create_by(name: company[:name])
+    #     @person  = @company.people.create(params[:person])
+    #
+    #     respond_to do |format|
+    #       format.html { redirect_to(person_list_url) }
+    #       format.js
+    #       format.xml  { render xml: @person.to_xml(include: @company) }
+    #     end
+    #   end
+    #
+    # If the client wants HTML, we just redirect them back to the person list. If they want JavaScript,
+    # then it is an Ajax request and we render the JavaScript template associated with this action.
+    # Lastly, if the client wants XML, we render the created person as XML, but with a twist: we also
+    # include the person's company in the rendered XML, so you get something like this:
+    #
+    #   <person>
+    #     <id>...</id>
+    #     ...
+    #     <company>
+    #       <id>...</id>
+    #       <name>...</name>
+    #       ...
+    #     </company>
+    #   </person>
+    #
+    # Note, however, the extra bit at the top of that action:
+    #
+    #   company  = params[:person].delete(:company)
+    #   @company = Company.find_or_create_by(name: company[:name])
+    #
+    # This is because the incoming XML document (if a web-service request is in process) can only contain a
+    # single root-node. So, we have to rearrange things so that the request looks like this (url-encoded):
+    #
+    #   person[name]=...&person[company][name]=...&...
+    #
+    # And, like this (xml-encoded):
+    #
+    #   <person>
+    #     <name>...</name>
+    #     <company>
+    #       <name>...</name>
+    #     </company>
+    #   </person>
+    #
+    # In other words, we make the request so that it operates on a single entity's person. Then, in the action,
+    # we extract the company data from the request, find or create the company, and then create the new person
+    # with the remaining data.
+    #
+    # Note that you can define your own XML parameter parser which would allow you to describe multiple entities
+    # in a single request (i.e., by wrapping them all in a single root node), but if you just go with the flow
+    # and accept Rails' defaults, life will be much easier.
+    #
+    # If you need to use a MIME type which isn't supported by default, you can register your own handlers in
+    # +config/initializers/mime_types.rb+ as follows.
+    #
+    #   Mime::Type.register "image/jpg", :jpg
+    #
+    # Respond to also allows you to specify a common block for different formats by using +any+:
+    #
+    #   def index
+    #     @people = Person.all
+    #
+    #     respond_to do |format|
+    #       format.html
+    #       format.any(:xml, :json) { render request.format.to_sym => @people }
+    #     end
+    #   end
+    #
+    # In the example above, if the format is xml, it will render:
+    #
+    #   render xml: @people
+    #
+    # Or if the format is json:
+    #
+    #   render json: @people
+    #
+    # Formats can have different variants.
+    #
+    # The request variant is a specialization of the request format, like <tt>:tablet</tt>,
+    # <tt>:phone</tt>, or <tt>:desktop</tt>.
+    #
+    # We often want to render different html/json/xml templates for phones,
+    # tablets, and desktop browsers. Variants make it easy.
+    #
+    # You can set the variant in a +before_action+:
+    #
+    #   request.variant = :tablet if request.user_agent =~ /iPad/
+    #
+    # Respond to variants in the action just like you respond to formats:
+    #
+    #   respond_to do |format|
+    #     format.html do |variant|
+    #       variant.tablet # renders app/views/projects/show.html+tablet.erb
+    #       variant.phone { extra_setup; render ... }
+    #       variant.none  { special_setup } # executed only if there is no variant set
+    #     end
+    #   end
+    #
+    # Provide separate templates for each format and variant:
+    #
+    #   app/views/projects/show.html.erb
+    #   app/views/projects/show.html+tablet.erb
+    #   app/views/projects/show.html+phone.erb
+    #
+    # When you're not sharing any code within the format, you can simplify defining variants
+    # using the inline syntax:
+    #
+    #   respond_to do |format|
+    #     format.js         { render "trash" }
+    #     format.html.phone { redirect_to progress_path }
+    #     format.html.none  { render "trash" }
+    #   end
+    #
+    # Variants also support common +any+/+all+ block that formats have.
+    #
+    # It works for both inline:
+    #
+    #   respond_to do |format|
+    #     format.html.any   { render html: "any"   }
+    #     format.html.phone { render html: "phone" }
+    #   end
+    #
+    # and block syntax:
+    #
+    #   respond_to do |format|
+    #     format.html do |variant|
+    #       variant.any(:tablet, :phablet){ render html: "any" }
+    #       variant.phone { render html: "phone" }
+    #     end
+    #   end
+    #
+    # You can also set an array of variants:
+    #
+    #   request.variant = [:tablet, :phone]
+    #
+    # This will work similarly to formats and MIME types negotiation. If there
+    # is no +:tablet+ variant declared, the +:phone+ variant will be used:
+    #
+    #   respond_to do |format|
+    #     format.html.none
+    #     format.html.phone # this gets rendered
+    #   end
+    def respond_to(*mimes)
+      raise ArgumentError, "respond_to takes either types or a block, never both" if mimes.any? && block_given?
+
+      collector = Collector.new(mimes, request.variant)
+      yield collector if block_given?
+
+      if format = collector.negotiate_format(request)
+        _process_format(format)
+        _set_rendered_content_type format
+        response = collector.response
+        response.call if response
+      else
+        raise ActionController::UnknownFormat
+      end
+    end
+
+    # A container for responses available from the current controller for
+    # requests for different mime-types sent to a particular action.
+    #
+    # The public controller methods +respond_to+ may be called with a block
+    # that is used to define responses to different mime-types, e.g.
+    # for +respond_to+ :
+    #
+    #   respond_to do |format|
+    #     format.html
+    #     format.xml { render xml: @people }
+    #   end
+    #
+    # In this usage, the argument passed to the block (+format+ above) is an
+    # instance of the ActionController::MimeResponds::Collector class. This
+    # object serves as a container in which available responses can be stored by
+    # calling any of the dynamically generated, mime-type-specific methods such
+    # as +html+, +xml+ etc on the Collector. Each response is represented by a
+    # corresponding block if present.
+    #
+    # A subsequent call to #negotiate_format(request) will enable the Collector
+    # to determine which specific mime-type it should respond with for the current
+    # request, with this response then being accessible by calling #response.
+    class Collector
+      include AbstractController::Collector
+      attr_accessor :format
+
+      def initialize(mimes, variant = nil)
+        @responses = {}
+        @variant = variant
+
+        mimes.each { |mime| @responses[Mime[mime]] = nil }
+      end
+
+      def any(*args, &block)
+        if args.any?
+          args.each { |type| send(type, &block) }
+        else
+          custom(Mime::ALL, &block)
+        end
+      end
+      alias :all :any
+
+      def custom(mime_type, &block)
+        mime_type = Mime::Type.lookup(mime_type.to_s) unless mime_type.is_a?(Mime::Type)
+        @responses[mime_type] ||= if block_given?
+          block
+        else
+          VariantCollector.new(@variant)
+        end
+      end
+
+      def response
+        response = @responses.fetch(format, @responses[Mime::ALL])
+        if response.is_a?(VariantCollector) # `format.html.phone` - variant inline syntax
+          response.variant
+        elsif response.nil? || response.arity == 0 # `format.html` - just a format, call its block
+          response
+        else # `format.html{ |variant| variant.phone }` - variant block syntax
+          variant_collector = VariantCollector.new(@variant)
+          response.call(variant_collector) # call format block with variants collector
+          variant_collector.variant
+        end
+      end
+
+      def negotiate_format(request)
+        @format = request.negotiate_mime(@responses.keys)
+      end
+
+      class VariantCollector #:nodoc:
+        def initialize(variant = nil)
+          @variant = variant
+          @variants = {}
+        end
+
+        def any(*args, &block)
+          if block_given?
+            if args.any? && args.none? { |a| a == @variant }
+              args.each { |v| @variants[v] = block }
+            else
+              @variants[:any] = block
+            end
+          end
+        end
+        alias :all :any
+
+        def method_missing(name, *args, &block)
+          @variants[name] = block if block_given?
+        end
+
+        def variant
+          if @variant.empty?
+            @variants[:none] || @variants[:any]
+          else
+            @variants[variant_key]
+          end
+        end
+
+        private
+          def variant_key
+            @variant.find { |variant| @variants.key?(variant) } || :any
+          end
+      end
+    end
+  end
+end

data/lib/action_controller/metal/parameter_encoding.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ActionController
+  # Specify binary encoding for parameters for a given action.
+  module ParameterEncoding
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      def inherited(klass) # :nodoc:
+        super
+        klass.setup_param_encode
+      end
+
+      def setup_param_encode # :nodoc:
+        @_parameter_encodings = {}
+      end
+
+      def binary_params_for?(action) # :nodoc:
+        @_parameter_encodings[action.to_s]
+      end
+
+      # Specify that a given action's parameters should all be encoded as
+      # ASCII-8BIT (it "skips" the encoding default of UTF-8).
+      #
+      # For example, a controller would use it like this:
+      #
+      #   class RepositoryController < ActionController::Base
+      #     skip_parameter_encoding :show
+      #
+      #     def show
+      #       @repo = Repository.find_by_filesystem_path params[:file_path]
+      #
+      #       # `repo_name` is guaranteed to be UTF-8, but was ASCII-8BIT, so
+      #       # tag it as such
+      #       @repo_name = params[:repo_name].force_encoding 'UTF-8'
+      #     end
+      #
+      #     def index
+      #       @repositories = Repository.all
+      #     end
+      #   end
+      #
+      # The show action in the above controller would have all parameter values
+      # encoded as ASCII-8BIT. This is useful in the case where an application
+      # must handle data but encoding of the data is unknown, like file system data.
+      def skip_parameter_encoding(action)
+        @_parameter_encodings[action.to_s] = true
+      end
+    end
+  end
+end

data/lib/action_controller/metal/params_wrapper.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/slice"
+require "active_support/core_ext/hash/except"
+require "active_support/core_ext/module/anonymous"
+require "action_dispatch/http/mime_type"
+
+module ActionController
+  # Wraps the parameters hash into a nested hash. This will allow clients to
+  # submit requests without having to specify any root elements.
+  #
+  # This functionality is enabled in +config/initializers/wrap_parameters.rb+
+  # and can be customized.
+  #
+  # You could also turn it on per controller by setting the format array to
+  # a non-empty array:
+  #
+  #     class UsersController < ApplicationController
+  #       wrap_parameters format: [:json, :xml, :url_encoded_form, :multipart_form]
+  #     end
+  #
+  # If you enable +ParamsWrapper+ for +:json+ format, instead of having to
+  # send JSON parameters like this:
+  #
+  #     {"user": {"name": "Konata"}}
+  #
+  # You can send parameters like this:
+  #
+  #     {"name": "Konata"}
+  #
+  # And it will be wrapped into a nested hash with the key name matching the
+  # controller's name. For example, if you're posting to +UsersController+,
+  # your new +params+ hash will look like this:
+  #
+  #     {"name" => "Konata", "user" => {"name" => "Konata"}}
+  #
+  # You can also specify the key in which the parameters should be wrapped to,
+  # and also the list of attributes it should wrap by using either +:include+ or
+  # +:exclude+ options like this:
+  #
+  #     class UsersController < ApplicationController
+  #       wrap_parameters :person, include: [:username, :password]
+  #     end
+  #
+  # On Active Record models with no +:include+ or +:exclude+ option set,
+  # it will only wrap the parameters returned by the class method
+  # <tt>attribute_names</tt>.
+  #
+  # If you're going to pass the parameters to an +ActiveModel+ object (such as
+  # <tt>User.new(params[:user])</tt>), you might consider passing the model class to
+  # the method instead. The +ParamsWrapper+ will actually try to determine the
+  # list of attribute names from the model and only wrap those attributes:
+  #
+  #     class UsersController < ApplicationController
+  #       wrap_parameters Person
+  #     end
+  #
+  # You still could pass +:include+ and +:exclude+ to set the list of attributes
+  # you want to wrap.
+  #
+  # By default, if you don't specify the key in which the parameters would be
+  # wrapped to, +ParamsWrapper+ will actually try to determine if there's
+  # a model related to it or not. This controller, for example:
+  #
+  #     class Admin::UsersController < ApplicationController
+  #     end
+  #
+  # will try to check if <tt>Admin::User</tt> or +User+ model exists, and use it to
+  # determine the wrapper key respectively. If both models don't exist,
+  # it will then fallback to use +user+ as the key.
+  module ParamsWrapper
+    extend ActiveSupport::Concern
+
+    EXCLUDE_PARAMETERS = %w(authenticity_token _method utf8)
+
+    require "mutex_m"
+
+    class Options < Struct.new(:name, :format, :include, :exclude, :klass, :model) # :nodoc:
+      include Mutex_m
+
+      def self.from_hash(hash)
+        name    = hash[:name]
+        format  = Array(hash[:format])
+        include = hash[:include] && Array(hash[:include]).collect(&:to_s)
+        exclude = hash[:exclude] && Array(hash[:exclude]).collect(&:to_s)
+        new name, format, include, exclude, nil, nil
+      end
+
+      def initialize(name, format, include, exclude, klass, model) # :nodoc:
+        super
+        @include_set = include
+        @name_set    = name
+      end
+
+      def model
+        super || synchronize { super || self.model = _default_wrap_model }
+      end
+
+      def include
+        return super if @include_set
+
+        m = model
+        synchronize do
+          return super if @include_set
+
+          @include_set = true
+
+          unless super || exclude
+            if m.respond_to?(:attribute_names) && m.attribute_names.any?
+              if m.respond_to?(:stored_attributes) && !m.stored_attributes.empty?
+                self.include = m.attribute_names + m.stored_attributes.values.flatten.map(&:to_s)
+              else
+                self.include = m.attribute_names
+              end
+
+              if m.respond_to?(:nested_attributes_options) && m.nested_attributes_options.keys.any?
+                self.include += m.nested_attributes_options.keys.map do |key|
+                  key.to_s.concat("_attributes")
+                end
+              end
+
+              self.include
+            end
+          end
+        end
+      end
+
+      def name
+        return super if @name_set
+
+        m = model
+        synchronize do
+          return super if @name_set
+
+          @name_set = true
+
+          unless super || klass.anonymous?
+            self.name = m ? m.to_s.demodulize.underscore :
+              klass.controller_name.singularize
+          end
+        end
+      end
+
+      private
+        # Determine the wrapper model from the controller's name. By convention,
+        # this could be done by trying to find the defined model that has the
+        # same singular name as the controller. For example, +UsersController+
+        # will try to find if the +User+ model exists.
+        #
+        # This method also does namespace lookup. Foo::Bar::UsersController will
+        # try to find Foo::Bar::User, Foo::User and finally User.
+        def _default_wrap_model
+          return nil if klass.anonymous?
+          model_name = klass.name.sub(/Controller$/, "").classify
+
+          begin
+            if model_klass = model_name.safe_constantize
+              model_klass
+            else
+              namespaces = model_name.split("::")
+              namespaces.delete_at(-2)
+              break if namespaces.last == model_name
+              model_name = namespaces.join("::")
+            end
+          end until model_klass
+
+          model_klass
+        end
+    end
+
+    included do
+      class_attribute :_wrapper_options, default: Options.from_hash(format: [])
+    end
+
+    module ClassMethods
+      def _set_wrapper_options(options)
+        self._wrapper_options = Options.from_hash(options)
+      end
+
+      # Sets the name of the wrapper key, or the model which +ParamsWrapper+
+      # would use to determine the attribute names from.
+      #
+      # ==== Examples
+      #   wrap_parameters format: :xml
+      #     # enables the parameter wrapper for XML format
+      #
+      #   wrap_parameters :person
+      #     # wraps parameters into +params[:person]+ hash
+      #
+      #   wrap_parameters Person
+      #     # wraps parameters by determining the wrapper key from Person class
+      #     (+person+, in this case) and the list of attribute names
+      #
+      #   wrap_parameters include: [:username, :title]
+      #     # wraps only +:username+ and +:title+ attributes from parameters.
+      #
+      #   wrap_parameters false
+      #     # disables parameters wrapping for this controller altogether.
+      #
+      # ==== Options
+      # * <tt>:format</tt> - The list of formats in which the parameters wrapper
+      #   will be enabled.
+      # * <tt>:include</tt> - The list of attribute names which parameters wrapper
+      #   will wrap into a nested hash.
+      # * <tt>:exclude</tt> - The list of attribute names which parameters wrapper
+      #   will exclude from a nested hash.
+      def wrap_parameters(name_or_model_or_options, options = {})
+        model = nil
+
+        case name_or_model_or_options
+        when Hash
+          options = name_or_model_or_options
+        when false
+          options = options.merge(format: [])
+        when Symbol, String
+          options = options.merge(name: name_or_model_or_options)
+        else
+          model = name_or_model_or_options
+        end
+
+        opts = Options.from_hash _wrapper_options.to_h.slice(:format).merge(options)
+        opts.model = model
+        opts.klass = self
+
+        self._wrapper_options = opts
+      end
+
+      # Sets the default wrapper key or model which will be used to determine
+      # wrapper key and attribute names. Called automatically when the
+      # module is inherited.
+      def inherited(klass)
+        if klass._wrapper_options.format.any?
+          params = klass._wrapper_options.dup
+          params.klass = klass
+          klass._wrapper_options = params
+        end
+        super
+      end
+    end
+
+    # Performs parameters wrapping upon the request. Called automatically
+    # by the metal call stack.
+    def process_action(*args)
+      if _wrapper_enabled?
+        wrapped_hash = _wrap_parameters request.request_parameters
+        wrapped_keys = request.request_parameters.keys
+        wrapped_filtered_hash = _wrap_parameters request.filtered_parameters.slice(*wrapped_keys)
+
+        # This will make the wrapped hash accessible from controller and view.
+        request.parameters.merge! wrapped_hash
+        request.request_parameters.merge! wrapped_hash
+
+        # This will display the wrapped hash in the log file.
+        request.filtered_parameters.merge! wrapped_filtered_hash
+      end
+      super
+    end
+
+    private
+
+      # Returns the wrapper key which will be used to store wrapped parameters.
+      def _wrapper_key
+        _wrapper_options.name
+      end
+
+      # Returns the list of enabled formats.
+      def _wrapper_formats
+        _wrapper_options.format
+      end
+
+      # Returns the list of parameters which will be selected for wrapped.
+      def _wrap_parameters(parameters)
+        { _wrapper_key => _extract_parameters(parameters) }
+      end
+
+      def _extract_parameters(parameters)
+        if include_only = _wrapper_options.include
+          parameters.slice(*include_only)
+        else
+          exclude = _wrapper_options.exclude || []
+          parameters.except(*(exclude + EXCLUDE_PARAMETERS))
+        end
+      end
+
+      # Checks if we should perform parameters wrapping.
+      def _wrapper_enabled?
+        return false unless request.has_content_type?
+
+        ref = request.content_mime_type.ref
+        _wrapper_formats.include?(ref) && _wrapper_key && !request.parameters.key?(_wrapper_key)
+      end
+  end
+end