actionpack 3.2.22.5 → 5.2.4

data/lib/action_controller/metal/mime_responds.rb

@@ -1,67 +1,9 @@
-require 'abstract_controller/collector'
-require 'active_support/core_ext/class/attribute'
-require 'active_support/core_ext/object/inclusion'
+# frozen_string_literal: true
+
+require "abstract_controller/collector"
 
 module ActionController #:nodoc:
   module MimeResponds
-    extend ActiveSupport::Concern
-
-    include ActionController::ImplicitRender
-
-    included do
-      class_attribute :responder, :mimes_for_respond_to
-      self.responder = ActionController::Responder
-      clear_respond_to
-    end
-
-    module ClassMethods
-      # Defines mime types that are rendered by default when invoking
-      # <tt>respond_with</tt>.
-      #
-      # Examples:
-      #
-      #   respond_to :html, :xml, :json
-      #
-      # Specifies that all actions in the controller respond to requests
-      # for <tt>:html</tt>, <tt>:xml</tt> and <tt>:json</tt>.
-      #
-      # To specify on per-action basis, use <tt>:only</tt> and
-      # <tt>:except</tt> with an array of actions or a single action:
-      #
-      #   respond_to :html
-      #   respond_to :xml, :json, :except => [ :edit ]
-      #
-      # This specifies that all actions respond to <tt>:html</tt>
-      # and all actions except <tt>:edit</tt> respond to <tt>:xml</tt> and
-      # <tt>:json</tt>.
-      #
-      #   respond_to :json, :only => :create
-      #
-      # This specifies that the <tt>:create</tt> action and no other responds
-      # to <tt>:json</tt>.
-      def respond_to(*mimes)
-        options = mimes.extract_options!
-
-        only_actions   = Array(options.delete(:only)).map(&:to_s)
-        except_actions = Array(options.delete(:except)).map(&:to_s)
-
-        new = mimes_for_respond_to.dup
-        mimes.each do |mime|
-          mime = mime.to_sym
-          new[mime]          = {}
-          new[mime][:only]   = only_actions   unless only_actions.empty?
-          new[mime][:except] = except_actions unless except_actions.empty?
-        end
-        self.mimes_for_respond_to = new.freeze
-      end
-
-      # Clear all mime types in <tt>respond_to</tt>.
-      #
-      def clear_respond_to
-        self.mimes_for_respond_to = ActiveSupport::OrderedHash.new.freeze
-      end
-    end
-
     # Without web-service support, an action which collects the data for displaying a list of people
     # might look something like this:
     #
@@ -69,6 +11,13 @@ module ActionController #:nodoc:
     #     @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
@@ -76,11 +25,12 @@ module ActionController #:nodoc:
     #
     #     respond_to do |format|
     #       format.html
-    #       format.xml { render :xml => @people.to_xml }
+    #       format.js
+    #       format.xml { render xml: @people }
     #     end
     #   end
     #
-    # What that says is, "if the client wants HTML in response to this action, just respond as we
+    # 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.)
     #
@@ -88,7 +38,7 @@ module ActionController #:nodoc:
     # (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])
+    #     @company = Company.find_or_create_by(name: params[:company][:name])
     #     @person  = @company.people.create(params[:person])
     #
     #     redirect_to(person_list_url)
@@ -98,13 +48,13 @@ module ActionController #:nodoc:
     #
     #   def create
     #     company  = params[:person].delete(:company)
-    #     @company = Company.find_or_create_by_name(company[:name])
+    #     @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) }
+    #       format.xml  { render xml: @person.to_xml(include: @company) }
     #     end
     #   end
     #
@@ -126,7 +76,7 @@ module ActionController #:nodoc:
     # 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])
+    #   @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):
@@ -151,11 +101,11 @@ module ActionController #:nodoc:
     # 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.
+    # +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:
+    # Respond to also allows you to specify a common block for different formats by using +any+:
     #
     #   def index
     #     @people = Person.all
@@ -168,126 +118,125 @@ module ActionController #:nodoc:
     #
     # In the example above, if the format is xml, it will render:
     #
-    #   render :xml => @people
+    #   render xml: @people
     #
     # Or if the format is json:
     #
-    #   render :json => @people
+    #   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>.
     #
-    # Since this is a common pattern, you can use the class method respond_to
-    # with the respond_with method to have the same results:
+    # We often want to render different html/json/xml templates for phones,
+    # tablets, and desktop browsers. Variants make it easy.
     #
-    #   class PeopleController < ApplicationController
-    #     respond_to :html, :xml, :json
+    # You can set the variant in a +before_action+:
     #
-    #     def index
-    #       @people = Person.all
-    #       respond_with(@people)
+    #   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
     #
-    # Be sure to check respond_with and respond_to documentation for more examples.
+    # Provide separate templates for each format and variant:
     #
-    def respond_to(*mimes, &block)
-      raise ArgumentError, "respond_to takes either types or a block, never both" if mimes.any? && block_given?
-
-      if collector = retrieve_collector_from_mimes(mimes, &block)
-        response = collector.response
-        response ? response.call : default_render({})
-      end
-    end
-
-    # respond_with wraps a resource around a responder for default representation.
-    # First it invokes respond_to, if a response cannot be found (ie. no block
-    # for the request was given and template was not available), it instantiates
-    # an ActionController::Responder with the controller and resource.
+    #   app/views/projects/show.html.erb
+    #   app/views/projects/show.html+tablet.erb
+    #   app/views/projects/show.html+phone.erb
     #
-    # ==== Example
+    # When you're not sharing any code within the format, you can simplify defining variants
+    # using the inline syntax:
     #
-    #   def index
-    #     @users = User.all
-    #     respond_with(@users)
+    #   respond_to do |format|
+    #     format.js         { render "trash" }
+    #     format.html.phone { redirect_to progress_path }
+    #     format.html.none  { render "trash" }
     #   end
     #
-    # It also accepts a block to be given. It's used to overwrite a default
-    # response:
+    # Variants also support common +any+/+all+ block that formats have.
     #
-    #   def create
-    #     @user = User.new(params[:user])
-    #     flash[:notice] = "User was successfully created." if @user.save
+    # It works for both inline:
+    #
+    #   respond_to do |format|
+    #     format.html.any   { render html: "any"   }
+    #     format.html.phone { render html: "phone" }
+    #   end
     #
-    #     respond_with(@user) do |format|
-    #       format.html { render }
+    # 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
     #
-    # All options given to respond_with are sent to the underlying responder,
-    # except for the option :responder itself. Since the responder interface
-    # is quite simple (it just needs to respond to call), you can even give
-    # a proc to it.
+    # You can also set an array of variants:
     #
-    # In order to use respond_with, first you need to declare the formats your
-    # controller responds to in the class level with a call to <tt>respond_to</tt>.
+    #   request.variant = [:tablet, :phone]
     #
-    def respond_with(*resources, &block)
-      raise "In order to use respond_with, first you need to declare the formats your " <<
-            "controller responds to in the class level" if self.class.mimes_for_respond_to.empty?
-
-      if collector = retrieve_collector_from_mimes(&block)
-        options = resources.size == 1 ? {} : resources.extract_options!
-        options[:default_response] = collector.response
-        (options.delete(:responder) || self.class.responder).call(self, resources, options)
-      end
-    end
-
-  protected
-
-    # Collect mimes declared in the class method respond_to valid for the
-    # current action.
+    # This will work similarly to formats and MIME types negotiation. If there
+    # is no +:tablet+ variant declared, the +:phone+ variant will be used:
     #
-    def collect_mimes_from_class_level #:nodoc:
-      action = action_name.to_s
-
-      self.class.mimes_for_respond_to.keys.select do |mime|
-        config = self.class.mimes_for_respond_to[mime]
-
-        if config[:except]
-          !action.in?(config[:except])
-        elsif config[:only]
-          action.in?(config[:only])
-        else
-          true
-        end
-      end
-    end
+    #   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?
 
-    # Collects mimes and return the response for the negotiated format. Returns
-    # nil if :not_acceptable was sent to the client.
-    #
-    def retrieve_collector_from_mimes(mimes=nil, &block) #:nodoc:
-      mimes ||= collect_mimes_from_class_level
-      collector = Collector.new(mimes)
-      block.call(collector) if block_given?
-      format = collector.negotiate_format(request)
+      collector = Collector.new(mimes, request.variant)
+      yield collector if block_given?
 
-      if format
-        self.content_type ||= format.to_s
-        lookup_context.formats = [format.to_sym]
-        lookup_context.rendered_format = lookup_context.formats.first
-        collector
+      if format = collector.negotiate_format(request)
+        _process_format(format)
+        _set_rendered_content_type format
+        response = collector.response
+        response.call if response
       else
-        head :not_acceptable
-        nil
+        raise ActionController::UnknownFormat
       end
     end
 
-    class Collector #:nodoc:
+    # 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 :order, :format
+      attr_accessor :format
 
-      def initialize(mimes)
-        @order, @responses = [], {}
-        mimes.each { |mime| send(mime) }
+      def initialize(mimes, variant = nil)
+        @responses = {}
+        @variant = variant
+
+        mimes.each { |mime| @responses[Mime[mime]] = nil }
       end
 
       def any(*args, &block)
@@ -301,16 +250,63 @@ module ActionController #:nodoc:
 
       def custom(mime_type, &block)
         mime_type = Mime::Type.lookup(mime_type.to_s) unless mime_type.is_a?(Mime::Type)
-        @order << mime_type
-        @responses[mime_type] ||= block
+        @responses[mime_type] ||= if block_given?
+          block
+        else
+          VariantCollector.new(@variant)
+        end
       end
 
       def response
-        @responses[format] || @responses[Mime::ALL]
+        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(order)
+        @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

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