actionpack 3.2.19 → 4.0.0

data/lib/action_controller/metal/live.rb

@@ -0,0 +1,175 @@
+require 'action_dispatch/http/response'
+require 'delegate'
+
+module ActionController
+  # Mix this module in to your controller, and all actions in that controller
+  # will be able to stream data to the client as it's written.
+  #
+  #   class MyController < ActionController::Base
+  #     include ActionController::Live
+  #
+  #     def stream
+  #       response.headers['Content-Type'] = 'text/event-stream'
+  #       100.times {
+  #         response.stream.write "hello world\n"
+  #         sleep 1
+  #       }
+  #     ensure
+  #       response.stream.close
+  #     end
+  #   end
+  #
+  # There are a few caveats with this use. You *cannot* write headers after the
+  # response has been committed (Response#committed? will return truthy).
+  # Calling +write+ or +close+ on the response stream will cause the response
+  # object to be committed. Make sure all headers are set before calling write
+  # or close on your stream.
+  #
+  # You *must* call close on your stream when you're finished, otherwise the
+  # socket may be left open forever.
+  #
+  # The final caveat is that your actions are executed in a separate thread than
+  # the main thread. Make sure your actions are thread safe, and this shouldn't
+  # be a problem (don't share state across threads, etc).
+  module Live
+    class Buffer < ActionDispatch::Response::Buffer #:nodoc:
+      def initialize(response)
+        @error_callback = nil
+        super(response, SizedQueue.new(10))
+      end
+
+      def write(string)
+        unless @response.committed?
+          @response.headers["Cache-Control"] = "no-cache"
+          @response.headers.delete "Content-Length"
+        end
+
+        super
+      end
+
+      def each
+        while str = @buf.pop
+          yield str
+        end
+      end
+
+      def close
+        super
+        @buf.push nil
+      end
+
+      def on_error(&block)
+        @error_callback = block
+      end
+
+      def call_on_error
+        @error_callback.call
+      end
+    end
+
+    class Response < ActionDispatch::Response #:nodoc: all
+      class Header < DelegateClass(Hash)
+        def initialize(response, header)
+          @response = response
+          super(header)
+        end
+
+        def []=(k,v)
+          if @response.committed?
+            raise ActionDispatch::IllegalStateError, 'header already sent'
+          end
+
+          super
+        end
+
+        def merge(other)
+          self.class.new @response, __getobj__.merge(other)
+        end
+
+        def to_hash
+          __getobj__.dup
+        end
+      end
+
+      def commit!
+        headers.freeze
+        super
+      end
+
+      private
+
+      def build_buffer(response, body)
+        buf = Live::Buffer.new response
+        body.each { |part| buf.write part }
+        buf
+      end
+
+      def merge_default_headers(original, default)
+        Header.new self, super
+      end
+
+      def handle_conditional_get!
+        super unless committed?
+      end
+    end
+
+    def process(name)
+      t1 = Thread.current
+      locals = t1.keys.map { |key| [key, t1[key]] }
+
+      # This processes the action in a child thread. It lets us return the
+      # response code and headers back up the rack stack, and still process
+      # the body in parallel with sending data to the client
+      Thread.new {
+        t2 = Thread.current
+        t2.abort_on_exception = true
+
+        # Since we're processing the view in a different thread, copy the
+        # thread locals from the main thread to the child thread. :'(
+        locals.each { |k,v| t2[k] = v }
+
+        begin
+          super(name)
+        rescue => e
+          begin
+            @_response.stream.write(ActionView::Base.streaming_completion_on_exception) if request.format == :html
+            @_response.stream.call_on_error
+          rescue => exception
+            log_error(exception)
+          ensure
+            log_error(e)
+            @_response.stream.close
+          end
+        ensure
+          @_response.commit!
+        end
+      }
+
+      @_response.await_commit
+    end
+
+    def log_error(exception)
+      logger = ActionController::Base.logger
+      return unless logger
+
+      message = "\n#{exception.class} (#{exception.message}):\n"
+      message << exception.annoted_source_code.to_s if exception.respond_to?(:annoted_source_code)
+      message << "  " << exception.backtrace.join("\n  ")
+      logger.fatal("#{message}\n\n")
+    end
+
+    def response_body=(body)
+      super
+      response.stream.close if response
+    end
+
+    def set_response!(request)
+      if request.env["HTTP_VERSION"] == "HTTP/1.0"
+        super
+      else
+        @_response         = Live::Response.new
+        @_response.request = request
+      end
+    end
+  end
+end

data/lib/action_controller/metal/mime_responds.rb

@@ -1,13 +1,10 @@
+require 'active_support/core_ext/array/extract_options'
 require 'abstract_controller/collector'
-require 'active_support/core_ext/class/attribute'
-require 'active_support/core_ext/object/inclusion'
 
 module ActionController #:nodoc:
   module MimeResponds
     extend ActiveSupport::Concern
 
-    include ActionController::ImplicitRender
-
     included do
       class_attribute :responder, :mimes_for_respond_to
       self.responder = ActionController::Responder
@@ -18,8 +15,6 @@ module ActionController #:nodoc:
       # 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
@@ -29,13 +24,13 @@ module ActionController #:nodoc:
       # <tt>:except</tt> with an array of actions or a single action:
       #
       #   respond_to :html
-      #   respond_to :xml, :json, :except => [ :edit ]
+      #   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
+      #   respond_to :json, only: :create
       #
       # This specifies that the <tt>:create</tt> action and no other responds
       # to <tt>:json</tt>.
@@ -58,7 +53,7 @@ module ActionController #:nodoc:
       # Clear all mime types in <tt>respond_to</tt>.
       #
       def clear_respond_to
-        self.mimes_for_respond_to = ActiveSupport::OrderedHash.new.freeze
+        self.mimes_for_respond_to = Hash.new.freeze
       end
     end
 
@@ -76,7 +71,7 @@ module ActionController #:nodoc:
     #
     #     respond_to do |format|
     #       format.html
-    #       format.xml { render :xml => @people.to_xml }
+    #       format.xml { render xml: @people }
     #     end
     #   end
     #
@@ -88,7 +83,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 +93,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 +121,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):
@@ -168,11 +163,11 @@ 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
     #
     # Since this is a common pattern, you can use the class method respond_to
     # with the respond_with method to have the same results:
@@ -186,31 +181,117 @@ module ActionController #:nodoc:
     #     end
     #   end
     #
-    # Be sure to check respond_with and respond_to documentation for more examples.
-    #
+    # Be sure to check the documentation of +respond_with+ and
+    # <tt>ActionController::MimeResponds.respond_to</tt> for more examples.
     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({})
+        response ? response.call : 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.
+    # For a given controller action, respond_with generates an appropriate
+    # response based on the mime-type requested by the client.
     #
-    # ==== Example
+    # If the method is called with just a resource, as in this example -
     #
-    #   def index
-    #     @users = User.all
-    #     respond_with(@users)
+    #   class PeopleController < ApplicationController
+    #     respond_to :html, :xml, :json
+    #
+    #     def index
+    #       @people = Person.all
+    #       respond_with @people
+    #     end
+    #   end
+    #
+    # then the mime-type of the response is typically selected based on the
+    # request's Accept header and the set of available formats declared
+    # by previous calls to the controller's class method +respond_to+. Alternatively
+    # the mime-type can be selected by explicitly setting <tt>request.format</tt> in
+    # the controller.
+    #
+    # If an acceptable format is not identified, the application returns a
+    # '406 - not acceptable' status. Otherwise, the default response is to render
+    # a template named after the current action and the selected format,
+    # e.g. <tt>index.html.erb</tt>. If no template is available, the behavior
+    # depends on the selected format:
+    #
+    # * for an html response - if the request method is +get+, an exception
+    #   is raised but for other requests such as +post+ the response
+    #   depends on whether the resource has any validation errors (i.e.
+    #   assuming that an attempt has been made to save the resource,
+    #   e.g. by a +create+ action) -
+    #   1. If there are no errors, i.e. the resource
+    #      was saved successfully, the response +redirect+'s to the resource
+    #      i.e. its +show+ action.
+    #   2. If there are validation errors, the response
+    #      renders a default action, which is <tt>:new</tt> for a
+    #      +post+ request or <tt>:edit</tt> for +patch+ or +put+.
+    #   Thus an example like this -
+    #
+    #     respond_to :html, :xml
+    #
+    #     def create
+    #       @user = User.new(params[:user])
+    #       flash[:notice] = 'User was successfully created.' if @user.save
+    #       respond_with(@user)
+    #     end
+    #
+    #   is equivalent, in the absence of <tt>create.html.erb</tt>, to -
+    #
+    #     def create
+    #       @user = User.new(params[:user])
+    #       respond_to do |format|
+    #         if @user.save
+    #           flash[:notice] = 'User was successfully created.'
+    #           format.html { redirect_to(@user) }
+    #           format.xml { render xml: @user }
+    #         else
+    #           format.html { render action: "new" }
+    #           format.xml { render xml: @user }
+    #         end
+    #       end
+    #     end
+    #
+    # * for a javascript request - if the template isn't found, an exception is
+    #   raised.
+    # * for other requests - i.e. data formats such as xml, json, csv etc, if
+    #   the resource passed to +respond_with+ responds to <code>to_<format></code>,
+    #   the method attempts to render the resource in the requested format
+    #   directly, e.g. for an xml request, the response is equivalent to calling 
+    #   <code>render xml: resource</code>.
+    #
+    # === Nested resources
+    #
+    # As outlined above, the +resources+ argument passed to +respond_with+
+    # can play two roles. It can be used to generate the redirect url
+    # for successful html requests (e.g. for +create+ actions when
+    # no template exists), while for formats other than html and javascript
+    # it is the object that gets rendered, by being converted directly to the
+    # required format (again assuming no template exists).
+    #
+    # For redirecting successful html requests, +respond_with+ also supports
+    # the use of nested resources, which are supplied in the same way as
+    # in <code>form_for</code> and <code>polymorphic_url</code>. For example -
+    #
+    #   def create
+    #     @project = Project.find(params[:project_id])
+    #     @task = @project.comments.build(params[:task])
+    #     flash[:notice] = 'Task was successfully created.' if @task.save
+    #     respond_with(@project, @task)
     #   end
     #
-    # It also accepts a block to be given. It's used to overwrite a default
-    # response:
+    # This would cause +respond_with+ to redirect to <code>project_task_url</code>
+    # instead of <code>task_url</code>. For request formats other than html or
+    # javascript, if multiple resources are passed in this way, it is the last
+    # one specified that is rendered.
+    #
+    # === Customizing response behavior
+    #
+    # Like +respond_to+, +respond_with+ may also be called with a block that
+    # can be used to overwrite any of the default responses, e.g. -
     #
     #   def create
     #     @user = User.new(params[:user])
@@ -221,16 +302,26 @@ module ActionController #:nodoc:
     #     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.
-    #
-    # 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>.
-    #
+    # The argument passed to the block is an ActionController::MimeResponds::Collector
+    # object which stores the responses for the formats defined within the
+    # block. Note that formats with responses defined explicitly in this way
+    # do not have to first be declared using the class method +respond_to+.
+    #
+    # Also, a hash passed to +respond_with+ immediately after the specified
+    # resource(s) is interpreted as a set of options relevant to all
+    # formats. Any option accepted by +render+ can be used, e.g.
+    #   respond_with @people, status: 200
+    # However, note that these options are ignored after an unsuccessful attempt
+    # to save a resource, e.g. when automatically rendering <tt>:new</tt>
+    # after a post request.
+    #
+    # Two additional options are relevant specifically to +respond_with+ -
+    # 1. <tt>:location</tt> - overwrites the default redirect location used after
+    #    a successful html +post+ request.
+    # 2. <tt>:action</tt> - overwrites the default render action used after an
+    #    unsuccessful html +post+ request.
     def respond_with(*resources, &block)
-      raise "In order to use respond_with, first you need to declare the formats your " <<
+      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)
@@ -244,7 +335,6 @@ module ActionController #:nodoc:
 
     # Collect mimes declared in the class method respond_to valid for the
     # current action.
-    #
     def collect_mimes_from_class_level #:nodoc:
       action = action_name.to_s
 
@@ -252,18 +342,21 @@ module ActionController #:nodoc:
         config = self.class.mimes_for_respond_to[mime]
 
         if config[:except]
-          !action.in?(config[:except])
+          !config[:except].include?(action)
         elsif config[:only]
-          action.in?(config[:only])
+          config[:only].include?(action)
         else
           true
         end
       end
     end
 
-    # Collects mimes and return the response for the negotiated format. Returns
-    # nil if :not_acceptable was sent to the client.
+    # Returns a Collector object containing the appropriate mime-type response
+    # for the current request, based on the available responses defined by a block.
+    # In typical usage this is the block passed to +respond_with+ or +respond_to+.
     #
+    # Sends :not_acceptable to the client and returns nil if no suitable format
+    # is available.
     def retrieve_collector_from_mimes(mimes=nil, &block) #:nodoc:
       mimes ||= collect_mimes_from_class_level
       collector = Collector.new(mimes)
@@ -276,12 +369,33 @@ module ActionController #:nodoc:
         lookup_context.rendered_format = lookup_context.formats.first
         collector
       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_with+ and +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
 
@@ -306,7 +420,7 @@ module ActionController #:nodoc:
       end
 
       def response
-        @responses[format] || @responses[Mime::ALL]
+        @responses.fetch(format, @responses[Mime::ALL])
       end
 
       def negotiate_format(request)