actionpack 7.1.3.4 → 7.2.0.beta1

data/lib/action_controller/metal/implicit_render.rb

@@ -1,33 +1,35 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionController
-  # = Action Controller Implicit Render
+  # # Action Controller Implicit Render
   #
-  # Handles implicit rendering for a controller action that does not
-  # explicitly respond with +render+, +respond_to+, +redirect+, or +head+.
+  # Handles implicit rendering for a controller action that does not explicitly
+  # respond with `render`, `respond_to`, `redirect`, or `head`.
   #
-  # For API controllers, the implicit response is always <tt>204 No Content</tt>.
+  # For API controllers, the implicit response is always `204 No Content`.
   #
-  # For all other controllers, we use these heuristics to decide whether to
-  # render a template, raise an error for a missing template, or respond with
-  # <tt>204 No Content</tt>:
+  # For all other controllers, we use these heuristics to decide whether to render
+  # a template, raise an error for a missing template, or respond with `204 No
+  # Content`:
   #
-  # First, if we DO find a template, it's rendered. Template lookup accounts
-  # for the action name, locales, format, variant, template handlers, and more
-  # (see +render+ for details).
+  # First, if we DO find a template, it's rendered. Template lookup accounts for
+  # the action name, locales, format, variant, template handlers, and more (see
+  # `render` for details).
   #
   # Second, if we DON'T find a template but the controller action does have
-  # templates for other formats, variants, etc., then we trust that you meant
-  # to provide a template for this response, too, and we raise
+  # templates for other formats, variants, etc., then we trust that you meant to
+  # provide a template for this response, too, and we raise
   # ActionController::UnknownFormat with an explanation.
   #
   # Third, if we DON'T find a template AND the request is a page load in a web
-  # browser (technically, a non-XHR GET request for an HTML response) where
-  # you reasonably expect to have rendered a template, then we raise
+  # browser (technically, a non-XHR GET request for an HTML response) where you
+  # reasonably expect to have rendered a template, then we raise
   # ActionController::MissingExactTemplate with an explanation.
   #
   # Finally, if we DON'T find a template AND the request isn't a browser page
-  # load, then we implicitly respond with <tt>204 No Content</tt>.
+  # load, then we implicitly respond with `204 No Content`.
   module ImplicitRender
     # :stopdoc:
     include BasicImplicitRender

data/lib/action_controller/metal/instrumentation.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "benchmark"
 require "abstract_controller/logger"
 
 module ActionController
-  # = Action Controller \Instrumentation
+  # # Action Controller Instrumentation
   #
-  # Adds instrumentation to several ends in ActionController::Base. It also provides
-  # some hooks related with process_action. This allows an ORM like Active Record
-  # and/or DataMapper to plug in ActionController and show related information.
+  # Adds instrumentation to several ends in ActionController::Base. It also
+  # provides some hooks related with process_action. This allows an ORM like
+  # Active Record and/or DataMapper to plug in ActionController and show related
+  # information.
   #
   # Check ActiveRecord::Railties::ControllerRuntime for an example.
   module Instrumentation
@@ -91,23 +94,23 @@ module ActionController
       # A hook which allows you to clean up any time, wrongly taken into account in
       # views, like database querying time.
       #
-      #   def cleanup_view_runtime
-      #     super - time_taken_in_something_expensive
-      #   end
+      #     def cleanup_view_runtime
+      #       super - time_taken_in_something_expensive
+      #     end
       def cleanup_view_runtime # :doc:
         yield
       end
 
-      # Every time after an action is processed, this method is invoked
-      # with the payload, so you can add more information.
+      # Every time after an action is processed, this method is invoked with the
+      # payload, so you can add more information.
       def append_info_to_payload(payload) # :doc:
         payload[:view_runtime] = view_runtime
       end
 
       module ClassMethods
-        # A hook which allows other frameworks to log what happened during
-        # controller process action. This method should return an array
-        # with the messages to be added.
+        # A hook which allows other frameworks to log what happened during controller
+        # process action. This method should return an array with the messages to be
+        # added.
         def log_process_action(payload) # :nodoc:
           messages, view_runtime = [], payload[:view_runtime]
           messages << ("Views: %.1fms" % view_runtime.to_f) if view_runtime

data/lib/action_controller/metal/live.rb

@@ -1,56 +1,58 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "action_dispatch/http/response"
 require "delegate"
 require "active_support/json"
 
 module ActionController
-  # = Action Controller \Live
+  # # Action Controller Live
   #
-  # Mix this module into your controller, and all actions in that controller
-  # will be able to stream data to the client as it's written.
+  # Mix this module into 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
+  #     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
+  #       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
-  #   end
   #
-  # There are a few caveats with this module. 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.
+  # There are a few caveats with this module. 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
+  # 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).
+  # the main thread. Make sure your actions are thread safe, and this shouldn't be
+  # a problem (don't share state across threads, etc).
   #
-  # Note that \Rails includes +Rack::ETag+ by default, which will buffer your
+  # Note that Rails includes `Rack::ETag` by default, which will buffer your
   # response. As a result, streaming responses may not work properly with Rack
-  # 2.2.x, and you may need to implement workarounds in your application.
-  # You can either set the +ETag+ or +Last-Modified+ response headers or remove
-  # +Rack::ETag+ from the middleware stack to address this issue.
+  # 2.2.x, and you may need to implement workarounds in your application. You can
+  # either set the `ETag` or `Last-Modified` response headers or remove
+  # `Rack::ETag` from the middleware stack to address this issue.
   #
-  # Here's an example of how you can set the +Last-Modified+ header if your Rack
+  # Here's an example of how you can set the `Last-Modified` header if your Rack
   # version is 2.2.x:
   #
-  #   def stream
-  #     response.headers["Content-Type"] = "text/event-stream"
-  #     response.headers["Last-Modified"] = Time.now.httpdate # Add this line if your Rack version is 2.2.x
-  #     ...
-  #   end
+  #     def stream
+  #       response.headers["Content-Type"] = "text/event-stream"
+  #       response.headers["Last-Modified"] = Time.now.httpdate # Add this line if your Rack version is 2.2.x
+  #       ...
+  #     end
   module Live
     extend ActiveSupport::Concern
 
@@ -66,44 +68,44 @@ module ActionController
       end
     end
 
-    # = Action Controller \Live Server Sent Events
+    # # Action Controller Live Server Sent Events
     #
-    # This class provides the ability to write an SSE (Server Sent Event)
-    # to an IO stream. The class is initialized with a stream and can be used
-    # to either write a JSON string or an object which can be converted to JSON.
+    # This class provides the ability to write an SSE (Server Sent Event) to an IO
+    # stream. The class is initialized with a stream and can be used to either write
+    # a JSON string or an object which can be converted to JSON.
     #
     # Writing an object will convert it into standard SSE format with whatever
     # options you have configured. You may choose to set the following options:
     #
-    #   1) Event. If specified, an event with this name will be dispatched on
-    #   the browser.
-    #   2) Retry. The reconnection time in milliseconds used when attempting
-    #   to send the event.
-    #   3) Id. If the connection dies while sending an SSE to the browser, then
-    #   the server will receive a +Last-Event-ID+ header with value equal to +id+.
+    #     1) Event. If specified, an event with this name will be dispatched on
+    #     the browser.
+    #     2) Retry. The reconnection time in milliseconds used when attempting
+    #     to send the event.
+    #     3) Id. If the connection dies while sending an SSE to the browser, then
+    #     the server will receive a +Last-Event-ID+ header with value equal to +id+.
     #
-    # After setting an option in the constructor of the SSE object, all future
-    # SSEs sent across the stream will use those options unless overridden.
+    # After setting an option in the constructor of the SSE object, all future SSEs
+    # sent across the stream will use those options unless overridden.
     #
     # Example Usage:
     #
-    #   class MyController < ActionController::Base
-    #     include ActionController::Live
+    #     class MyController < ActionController::Base
+    #       include ActionController::Live
     #
-    #     def index
-    #       response.headers['Content-Type'] = 'text/event-stream'
-    #       sse = SSE.new(response.stream, retry: 300, event: "event-name")
-    #       sse.write({ name: 'John'})
-    #       sse.write({ name: 'John'}, id: 10)
-    #       sse.write({ name: 'John'}, id: 10, event: "other-event")
-    #       sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
-    #     ensure
-    #       sse.close
+    #       def index
+    #         response.headers['Content-Type'] = 'text/event-stream'
+    #         sse = SSE.new(response.stream, retry: 300, event: "event-name")
+    #         sse.write({ name: 'John'})
+    #         sse.write({ name: 'John'}, id: 10)
+    #         sse.write({ name: 'John'}, id: 10, event: "other-event")
+    #         sse.write({ name: 'John'}, id: 10, event: "other-event", retry: 500)
+    #       ensure
+    #         sse.close
+    #       end
     #     end
-    #   end
     #
-    # Note: SSEs are not currently supported by IE. However, they are supported
-    # by Chrome, Firefox, Opera, and Safari.
+    # Note: SSEs are not currently supported by IE. However, they are supported by
+    # Chrome, Firefox, Opera, and Safari.
     class SSE
       PERMITTED_OPTIONS = %w( retry event id )
 
@@ -153,10 +155,9 @@ module ActionController
 
       # Ignore that the client has disconnected.
       #
-      # If this value is `true`, calling `write` after the client
-      # disconnects will result in the written content being silently
-      # discarded. If this value is `false` (the default), a
-      # ClientDisconnected exception will be raised.
+      # If this value is `true`, calling `write` after the client disconnects will
+      # result in the written content being silently discarded. If this value is
+      # `false` (the default), a ClientDisconnected exception will be raised.
       attr_accessor :ignore_disconnect
 
       def initialize(response)
@@ -167,9 +168,10 @@ module ActionController
         @ignore_disconnect = false
       end
 
-      # ActionDispatch::Response delegates #to_ary to the internal ActionDispatch::Response::Buffer,
-      # defining #to_ary is an indicator that the response body can be buffered and/or cached by
-      # Rack middlewares, this is not the case for Live responses so we undefine it for this Buffer subclass.
+      # ActionDispatch::Response delegates #to_ary to the internal
+      # ActionDispatch::Response::Buffer, defining #to_ary is an indicator that the
+      # response body can be buffered and/or cached by Rack middlewares, this is not
+      # the case for Live responses so we undefine it for this Buffer subclass.
       undef_method :to_ary
 
       def write(string)
@@ -184,21 +186,20 @@ module ActionController
           @buf.clear
 
           unless @ignore_disconnect
-            # Raise ClientDisconnected, which is a RuntimeError (not an
-            # IOError), because that's more appropriate for something beyond
-            # the developer's control.
+            # Raise ClientDisconnected, which is a RuntimeError (not an IOError), because
+            # that's more appropriate for something beyond the developer's control.
             raise ClientDisconnected, "client disconnected"
           end
         end
       end
 
-      # Same as +write+ but automatically include a newline at the end of the string.
+      # Same as `write` but automatically include a newline at the end of the string.
       def writeln(string)
         write string.end_with?("\n") ? string : "#{string}\n"
       end
 
-      # Write a 'close' event to the buffer; the producer/writing thread
-      # uses this to notify us that it's finished supplying content.
+      # Write a 'close' event to the buffer; the producer/writing thread uses this to
+      # notify us that it's finished supplying content.
       #
       # See also #abort.
       def close
@@ -209,9 +210,8 @@ module ActionController
         end
       end
 
-      # Inform the producer/writing thread that the client has
-      # disconnected; the reading thread is no longer interested in
-      # anything that's being written.
+      # Inform the producer/writing thread that the client has disconnected; the
+      # reading thread is no longer interested in anything that's being written.
       #
       # See also #close.
       def abort
@@ -223,8 +223,8 @@ module ActionController
 
       # Is the client still connected and waiting for content?
       #
-      # The result of calling `write` when this is `false` is determined
-      # by `ignore_disconnect`.
+      # The result of calling `write` when this is `false` is determined by
+      # `ignore_disconnect`.
       def connected?
         !@aborted
       end
@@ -275,15 +275,15 @@ module ActionController
       locals = t1.keys.map { |key| [key, t1[key]] }
 
       error = nil
-      # 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.
+      # 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.
       new_controller_thread {
         ActiveSupport::Dependencies.interlock.running do
           t2 = Thread.current
 
-          # Since we're processing the view in a different thread, copy the
-          # thread locals from the main thread to the child thread. :'(
+          # 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 }
           ActiveSupport::IsolatedExecutionState.share_with(t1)
 
@@ -321,46 +321,52 @@ module ActionController
       response.close if response
     end
 
-    # Sends a stream to the browser, which is helpful when you're generating exports or other running data where you
-    # don't want the entire file buffered in memory first. Similar to send_data, but where the data is generated live.
+    # Sends a stream to the browser, which is helpful when you're generating exports
+    # or other running data where you don't want the entire file buffered in memory
+    # first. Similar to send_data, but where the data is generated live.
     #
     # Options:
-    # * <tt>:filename</tt> - suggests a filename for the browser to use.
-    # * <tt>:type</tt> - specifies an HTTP content type.
-    #   You can specify either a string or a symbol for a registered type with <tt>Mime::Type.register</tt>, for example :json.
-    #   If omitted, type will be inferred from the file extension specified in <tt>:filename</tt>.
-    #   If no content type is registered for the extension, the default type 'application/octet-stream' will be used.
-    # * <tt>:disposition</tt> - specifies whether the file will be shown inline or downloaded.
-    #   Valid values are 'inline' and 'attachment' (default).
+    # *   `:filename` - suggests a filename for the browser to use.
+    # *   `:type` - specifies an HTTP content type. You can specify either a string
+    #     or a symbol for a registered type with `Mime::Type.register`, for example
+    #     :json. If omitted, type will be inferred from the file extension specified
+    #     in `:filename`. If no content type is registered for the extension, the
+    #     default type 'application/octet-stream' will be used.
+    # *   `:disposition` - specifies whether the file will be shown inline or
+    #     downloaded. Valid values are 'inline' and 'attachment' (default).
+    #
     #
     # Example of generating a csv export:
     #
-    #    send_stream(filename: "subscribers.csv") do |stream|
-    #      stream.write "email_address,updated_at\n"
+    #     send_stream(filename: "subscribers.csv") do |stream|
+    #       stream.write "email_address,updated_at\n"
     #
-    #      @subscribers.find_each do |subscriber|
-    #        stream.write "#{subscriber.email_address},#{subscriber.updated_at}\n"
-    #      end
-    #    end
+    #       @subscribers.find_each do |subscriber|
+    #         stream.write "#{subscriber.email_address},#{subscriber.updated_at}\n"
+    #       end
+    #     end
     def send_stream(filename:, disposition: "attachment", type: nil)
-      response.headers["Content-Type"] =
-        (type.is_a?(Symbol) ? Mime[type].to_s : type) ||
-        Mime::Type.lookup_by_extension(File.extname(filename).downcase.delete("."))&.to_s ||
-        "application/octet-stream"
+      payload = { filename: filename, disposition: disposition, type: type }
+      ActiveSupport::Notifications.instrument("send_stream.action_controller", payload) do
+        response.headers["Content-Type"] =
+          (type.is_a?(Symbol) ? Mime[type].to_s : type) ||
+          Mime::Type.lookup_by_extension(File.extname(filename).downcase.delete("."))&.to_s ||
+          "application/octet-stream"
 
-      response.headers["Content-Disposition"] =
-        ActionDispatch::Http::ContentDisposition.format(disposition: disposition, filename: filename)
+        response.headers["Content-Disposition"] =
+          ActionDispatch::Http::ContentDisposition.format(disposition: disposition, filename: filename)
 
-      yield response.stream
+        yield response.stream
+      end
     ensure
       response.stream.close
     end
 
     private
-      # Spawn a new thread to serve up the controller in. This is to get
-      # around the fact that Rack isn't based around IOs and we need to use
-      # a thread to stream data from the response bodies. Nobody should call
-      # this method except in Rails internals. Seriously!
+      # Spawn a new thread to serve up the controller in. This is to get around the
+      # fact that Rack isn't based around IOs and we need to use a thread to stream
+      # data from the response bodies. Nobody should call this method except in Rails
+      # internals. Seriously!
       def new_controller_thread # :nodoc:
         Thread.new {
           t2 = Thread.current

data/lib/action_controller/metal/logging.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionController
   module Logging
     extend ActiveSupport::Concern
@@ -7,10 +9,10 @@ module ActionController
     module ClassMethods
       # Set a different log level per request.
       #
-      #   # Use the debug log level if a particular cookie is set.
-      #   class ApplicationController < ActionController::Base
-      #     log_at :debug, if: -> { cookies[:debug] }
-      #   end
+      #     # Use the debug log level if a particular cookie is set.
+      #     class ApplicationController < ActionController::Base
+      #       log_at :debug, if: -> { cookies[:debug] }
+      #     end
       #
       def log_at(level, **options)
         around_action ->(_, action) { logger.log_at(level, &action) }, **options