actionpack 7.1.3.2 → 7.2.0.beta1

data/lib/action_controller/metal/data_streaming.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "action_controller/metal/exceptions"
 require "action_dispatch/http/content_disposition"
 
 module ActionController # :nodoc:
-  # = Action Controller Data \Streaming
+  # # Action Controller Data Streaming
   #
   # Methods for sending arbitrary data and for streaming files to the browser,
   # instead of rendering.
@@ -17,57 +19,60 @@ module ActionController # :nodoc:
     DEFAULT_SEND_FILE_DISPOSITION = "attachment" # :nodoc:
 
     private
-      # Sends the file. This uses a server-appropriate method (such as +X-Sendfile+)
-      # via the +Rack::Sendfile+ middleware. The header to use is set via
-      # +config.action_dispatch.x_sendfile_header+.
-      # Your server can also configure this for you by setting the +X-Sendfile-Type+ header.
+      # Sends the file. This uses a server-appropriate method (such as `X-Sendfile`)
+      # via the `Rack::Sendfile` middleware. The header to use is set via
+      # `config.action_dispatch.x_sendfile_header`. Your server can also configure
+      # this for you by setting the `X-Sendfile-Type` header.
       #
-      # Be careful to sanitize the path parameter if it is coming from a web
-      # page. <tt>send_file(params[:path])</tt> allows a malicious user to
-      # download any file on your server.
+      # Be careful to sanitize the path parameter if it is coming from a web page.
+      # `send_file(params[:path])` allows a malicious user to download any file on
+      # your server.
       #
       # Options:
-      # * <tt>:filename</tt> - suggests a filename for the browser to use.
-      #   Defaults to <tt>File.basename(path)</tt>.
-      # * <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, the 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 <tt>"inline"</tt> and <tt>"attachment"</tt> (default).
-      # * <tt>:status</tt> - specifies the status code to send with the response. Defaults to 200.
-      # * <tt>:url_based_filename</tt> - set to +true+ if you want the browser to guess the filename from
-      #   the URL, which is necessary for i18n filenames on certain browsers
-      #   (setting <tt>:filename</tt> overrides this option).
-      #
-      # The default +Content-Type+ and +Content-Disposition+ headers are
-      # set to download arbitrary binary files in as many browsers as
-      # possible. IE versions 4, 5, 5.5, and 6 are all known to have
-      # a variety of quirks (especially when downloading over SSL).
+      # *   `:filename` - suggests a filename for the browser to use. Defaults to
+      #     `File.basename(path)`.
+      # *   `: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, the 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).
+      # *   `:status` - specifies the status code to send with the response. Defaults
+      #     to 200.
+      # *   `:url_based_filename` - set to `true` if you want the browser to guess the
+      #     filename from the URL, which is necessary for i18n filenames on certain
+      #     browsers (setting `:filename` overrides this option).
+      #
+      #
+      # The default `Content-Type` and `Content-Disposition` headers are set to
+      # download arbitrary binary files in as many browsers as possible. IE versions
+      # 4, 5, 5.5, and 6 are all known to have a variety of quirks (especially when
+      # downloading over SSL).
       #
       # Simple download:
       #
-      #   send_file '/path/to.zip'
+      #     send_file '/path/to.zip'
       #
       # Show a JPEG in the browser:
       #
-      #   send_file '/path/to.jpeg', type: 'image/jpeg', disposition: 'inline'
+      #     send_file '/path/to.jpeg', type: 'image/jpeg', disposition: 'inline'
       #
       # Show a 404 page in the browser:
       #
-      #   send_file '/path/to/404.html', type: 'text/html; charset=utf-8', disposition: 'inline', status: 404
+      #     send_file '/path/to/404.html', type: 'text/html; charset=utf-8', disposition: 'inline', status: 404
       #
-      # You can use other <tt>Content-*</tt> HTTP headers to provide additional
-      # information to the client. See MDN for a
-      # {list of HTTP headers}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers].
+      # You can use other `Content-*` HTTP headers to provide additional information
+      # to the client. See MDN for a [list of HTTP
+      # headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers).
       #
-      # Also be aware that the document may be cached by proxies and browsers.
-      # The +Pragma+ and +Cache-Control+ headers declare how the file may be cached
-      # by intermediaries. They default to require clients to validate with
-      # the server before releasing cached responses. See
-      # https://www.mnot.net/cache_docs/ for an overview of web caching and
-      # {RFC 9111}[https://www.rfc-editor.org/rfc/rfc9111.html#name-cache-control]
-      # for the +Cache-Control+ header spec.
+      # Also be aware that the document may be cached by proxies and browsers. The
+      # `Pragma` and `Cache-Control` headers declare how the file may be cached by
+      # intermediaries. They default to require clients to validate with the server
+      # before releasing cached responses. See https://www.mnot.net/cache_docs/ for an
+      # overview of web caching and [RFC
+      # 9111](https://www.rfc-editor.org/rfc/rfc9111.html#name-cache-control) for the
+      # `Cache-Control` header spec.
       def send_file(path, options = {}) # :doc:
         raise MissingFile, "Cannot read file #{path}" unless File.file?(path) && File.readable?(path)
 
@@ -79,35 +84,39 @@ module ActionController # :nodoc:
         response.send_file path
       end
 
-      # Sends the given binary data to the browser. This method is similar to
-      # <tt>render plain: data</tt>, but also allows you to specify whether
-      # the browser should display the response as a file attachment (i.e. in a
-      # download dialog) or as inline data. You may also set the content type,
-      # the file name, and other things.
+      # Sends the given binary data to the browser. This method is similar to `render
+      # plain: data`, but also allows you to specify whether the browser should
+      # display the response as a file attachment (i.e. in a download dialog) or as
+      # inline data. You may also set the content type, the file name, and other
+      # things.
       #
       # Options:
-      # * <tt>:filename</tt> - suggests a filename for the browser to use.
-      # * <tt>:type</tt> - specifies an HTTP content type. Defaults to +application/octet-stream+.
-      #   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 <tt>"inline"</tt> and <tt>"attachment"</tt> (default).
-      # * <tt>:status</tt> - specifies the status code to send with the response. Defaults to 200.
+      # *   `:filename` - suggests a filename for the browser to use.
+      # *   `:type` - specifies an HTTP content type. Defaults to
+      #     `application/octet-stream`. 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).
+      # *   `:status` - specifies the status code to send with the response. Defaults
+      #     to 200.
+      #
       #
       # Generic data download:
       #
-      #   send_data buffer
+      #     send_data buffer
       #
       # Download a dynamically-generated tarball:
       #
-      #   send_data generate_tgz('dir'), filename: 'dir.tgz'
+      #     send_data generate_tgz('dir'), filename: 'dir.tgz'
       #
       # Display an image Active Record in the browser:
       #
-      #   send_data image.data, type: image.content_type, disposition: 'inline'
+      #     send_data image.data, type: image.content_type, disposition: 'inline'
       #
-      # See +send_file+ for more information on HTTP <tt>Content-*</tt> headers and caching.
+      # See `send_file` for more information on HTTP `Content-*` headers and caching.
       def send_data(data, options = {}) # :doc:
         send_file_headers! options
         render options.slice(:status, :content_type).merge(body: data)

data/lib/action_controller/metal/default_headers.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionController
-  # = Action Controller Default Headers
+  # # Action Controller Default Headers
   #
-  # Allows configuring default headers that will be automatically merged into
-  # each response.
+  # Allows configuring default headers that will be automatically merged into each
+  # response.
   module DefaultHeaders
     extend ActiveSupport::Concern
 

data/lib/action_controller/metal/etag_with_flash.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionController
-  # = Action Controller Etag With \Flash
+  # # Action Controller Etag With Flash
   #
   # When you're using the flash, it's generally used as a conditional on the view.
   # This means the content of the view depends on the flash. Which in turn means

data/lib/action_controller/metal/etag_with_template_digest.rb

@@ -1,24 +1,26 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionController
-  # = Action Controller Etag With Template \Digest
+  # # Action Controller Etag With Template Digest
   #
-  # When our views change, they should bubble up into HTTP cache freshness
-  # and bust browser caches. So the template digest for the current action
-  # is automatically included in the ETag.
+  # When our views change, they should bubble up into HTTP cache freshness and
+  # bust browser caches. So the template digest for the current action is
+  # automatically included in the ETag.
   #
   # Enabled by default for apps that use Action View. Disable by setting
   #
-  #   config.action_controller.etag_with_template_digest = false
+  #     config.action_controller.etag_with_template_digest = false
   #
-  # Override the template to digest by passing +:template+ to +fresh_when+
-  # and +stale?+ calls. For example:
+  # Override the template to digest by passing `:template` to `fresh_when` and
+  # `stale?` calls. For example:
   #
-  #   # We're going to render widgets/show, not posts/show
-  #   fresh_when @post, template: 'widgets/show'
+  #     # We're going to render widgets/show, not posts/show
+  #     fresh_when @post, template: 'widgets/show'
   #
-  #   # We're not going to render a template, so omit it from the ETag.
-  #   fresh_when @post, template: false
+  #     # We're not going to render a template, so omit it from the ETag.
+  #     fresh_when @post, template: false
   #
   module EtagWithTemplateDigest
     extend ActiveSupport::Concern
@@ -40,10 +42,10 @@ module ActionController
         end
       end
 
-      # Pick the template digest to include in the ETag. If the +:template+ option
-      # is present, use the named template. If +:template+ is +nil+ or absent, use
-      # the default controller/action template. If +:template+ is false, omit the
-      # template digest from the ETag.
+      # Pick the template digest to include in the ETag. If the `:template` option is
+      # present, use the named template. If `:template` is `nil` or absent, use the
+      # default controller/action template. If `:template` is false, omit the template
+      # digest from the ETag.
       def pick_template_for_etag(options)
         unless options[:template] == false
           options[:template] || lookup_context.find_all(action_name, _prefixes).first&.virtual_path

data/lib/action_controller/metal/exceptions.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionController
   class ActionControllerError < StandardError # :nodoc:
   end
@@ -73,16 +75,16 @@ module ActionController
   class UnknownFormat < ActionControllerError # :nodoc:
   end
 
-  # Raised when a nested respond_to is triggered and the content types of each
-  # are incompatible. For example:
+  # Raised when a nested respond_to is triggered and the content types of each are
+  # incompatible. For example:
   #
-  #  respond_to do |outer_type|
-  #    outer_type.js do
-  #      respond_to do |inner_type|
-  #        inner_type.html { render body: "HTML" }
-  #      end
-  #    end
-  #  end
+  #     respond_to do |outer_type|
+  #       outer_type.js do
+  #         respond_to do |inner_type|
+  #           inner_type.html { render body: "HTML" }
+  #         end
+  #       end
+  #     end
   class RespondToMismatchError < ActionControllerError
     DEFAULT_MESSAGE = "respond_to was called multiple times and matched with conflicting formats in this action. Please note that you may only call respond_to and match on a single format per action."
 

data/lib/action_controller/metal/flash.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionController # :nodoc:
   module Flash
     extend ActiveSupport::Concern
@@ -13,19 +15,19 @@ module ActionController # :nodoc:
 
     module ClassMethods
       # Creates new flash types. You can pass as many types as you want to create
-      # flash types other than the default <tt>alert</tt> and <tt>notice</tt> in
-      # your controllers and views. For instance:
+      # flash types other than the default `alert` and `notice` in your controllers
+      # and views. For instance:
       #
-      #   # in application_controller.rb
-      #   class ApplicationController < ActionController::Base
-      #     add_flash_types :warning
-      #   end
+      #     # in application_controller.rb
+      #     class ApplicationController < ActionController::Base
+      #       add_flash_types :warning
+      #     end
       #
-      #   # in your controller
-      #   redirect_to user_path(@user), warning: "Incomplete profile"
+      #     # in your controller
+      #     redirect_to user_path(@user), warning: "Incomplete profile"
       #
-      #   # in your view
-      #   <%= warning %>
+      #     # in your view
+      #     <%= warning %>
       #
       # This method will automatically define a new method for each of the given
       # names, and it will be available in your views.

data/lib/action_controller/metal/head.rb

@@ -1,23 +1,25 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionController
   module Head
-    # Returns a response that has no content (merely headers). The options
-    # argument is interpreted to be a hash of header names and values.
-    # This allows you to easily return a response that consists only of
-    # significant headers:
+    # Returns a response that has no content (merely headers). The options argument
+    # is interpreted to be a hash of header names and values. This allows you to
+    # easily return a response that consists only of significant headers:
     #
-    #   head :created, location: person_path(@person)
+    #     head :created, location: person_path(@person)
     #
-    #   head :created, location: @person
+    #     head :created, location: @person
     #
     # It can also be used to return exceptional conditions:
     #
-    #   return head(:method_not_allowed) unless request.post?
-    #   return head(:bad_request) unless valid_request?
-    #   render
+    #     return head(:method_not_allowed) unless request.post?
+    #     return head(:bad_request) unless valid_request?
+    #     render
     #
-    # See +Rack::Utils::SYMBOL_TO_STATUS_CODE+ for a full list of valid +status+ symbols.
+    # See `Rack::Utils::SYMBOL_TO_STATUS_CODE` for a full list of valid `status`
+    # symbols.
     def head(status, options = nil)
       if status.is_a?(Hash)
         raise ArgumentError, "#{status.inspect} is not a valid value for `status`."

data/lib/action_controller/metal/helpers.rb

@@ -1,59 +1,64 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionController
-  # = Action Controller \Helpers
+  # # Action Controller Helpers
   #
-  # The \Rails framework provides a large number of helpers for working with assets, dates, forms,
-  # numbers and model objects, to name a few. These helpers are available to all templates
-  # by default.
+  # The Rails framework provides a large number of helpers for working with
+  # assets, dates, forms, numbers and model objects, to name a few. These helpers
+  # are available to all templates by default.
   #
-  # In addition to using the standard template helpers provided, creating custom helpers to
-  # extract complicated logic or reusable functionality is strongly encouraged. By default, each controller
-  # will include all helpers. These helpers are only accessible on the controller through <tt>#helpers</tt>
+  # In addition to using the standard template helpers provided, creating custom
+  # helpers to extract complicated logic or reusable functionality is strongly
+  # encouraged. By default, each controller will include all helpers. These
+  # helpers are only accessible on the controller through `#helpers`
   #
-  # In previous versions of \Rails the controller will include a helper which
-  # matches the name of the controller, e.g., <tt>MyController</tt> will automatically
-  # include <tt>MyHelper</tt>. You can revert to the old behavior with the following:
+  # In previous versions of Rails the controller will include a helper which
+  # matches the name of the controller, e.g., `MyController` will automatically
+  # include `MyHelper`. You can revert to the old behavior with the following:
   #
-  #    # config/application.rb
-  #    class Application < Rails::Application
-  #      config.action_controller.include_all_helpers = false
-  #    end
+  #     # config/application.rb
+  #     class Application < Rails::Application
+  #       config.action_controller.include_all_helpers = false
+  #     end
   #
-  # Additional helpers can be specified using the +helper+ class method in ActionController::Base or any
-  # controller which inherits from it.
+  # Additional helpers can be specified using the `helper` class method in
+  # ActionController::Base or any controller which inherits from it.
   #
-  # The +to_s+ method from the \Time class can be wrapped in a helper method to display a custom message if
-  # a \Time object is blank:
+  # The `to_s` method from the Time class can be wrapped in a helper method to
+  # display a custom message if a Time object is blank:
   #
-  #   module FormattedTimeHelper
-  #     def format_time(time, format=:long, blank_message="&nbsp;")
-  #       time.blank? ? blank_message : time.to_fs(format)
+  #     module FormattedTimeHelper
+  #       def format_time(time, format=:long, blank_message="&nbsp;")
+  #         time.blank? ? blank_message : time.to_fs(format)
+  #       end
   #     end
-  #   end
   #
-  # FormattedTimeHelper can now be included in a controller, using the +helper+ class method:
+  # FormattedTimeHelper can now be included in a controller, using the `helper`
+  # class method:
   #
-  #   class EventsController < ActionController::Base
-  #     helper FormattedTimeHelper
-  #     def index
-  #       @events = Event.all
+  #     class EventsController < ActionController::Base
+  #       helper FormattedTimeHelper
+  #       def index
+  #         @events = Event.all
+  #       end
   #     end
-  #   end
   #
-  # Then, in any view rendered by <tt>EventsController</tt>, the <tt>format_time</tt> method can be called:
+  # Then, in any view rendered by `EventsController`, the `format_time` method can
+  # be called:
   #
-  #   <% @events.each do |event| -%>
-  #     <p>
-  #       <%= format_time(event.time, :short, "N/A") %> | <%= event.name %>
-  #     </p>
-  #   <% end -%>
+  #     <% @events.each do |event| -%>
+  #       <p>
+  #         <%= format_time(event.time, :short, "N/A") %> | <%= event.name %>
+  #       </p>
+  #     <% end -%>
   #
-  # Finally, assuming we have two event instances, one which has a time and one which does not,
-  # the output might look like this:
+  # Finally, assuming we have two event instances, one which has a time and one
+  # which does not, the output might look like this:
   #
-  #   23 Aug 11:30 | Carolina Railhawks Soccer Match
-  #   N/A | Carolina Railhawks Training Workshop
+  #     23 Aug 11:30 | Carolina Railhawks Soccer Match
+  #     N/A | Carolina Railhawks Training Workshop
   #
   module Helpers
     extend ActiveSupport::Concern
@@ -68,23 +73,24 @@ module ActionController
 
     module ClassMethods
       # Declares helper accessors for controller attributes. For example, the
-      # following adds new +name+ and <tt>name=</tt> instance methods to a
-      # controller and makes them available to the view:
-      #   attr_accessor :name
-      #   helper_attr :name
+      # following adds new `name` and `name=` instance methods to a controller and
+      # makes them available to the view:
+      #     attr_accessor :name
+      #     helper_attr :name
+      #
+      # #### Parameters
+      # *   `attrs` - Names of attributes to be converted into helpers.
       #
-      # ==== Parameters
-      # * <tt>attrs</tt> - Names of attributes to be converted into helpers.
       def helper_attr(*attrs)
         attrs.flatten.each { |attr| helper_method(attr, "#{attr}=") }
       end
 
       # Provides a proxy to access helper methods from outside the view.
       #
-      # Note that the proxy is rendered under a different view context.
-      # This may cause incorrect behavior with capture methods. Consider
-      # using {helper}[rdoc-ref:AbstractController::Helpers::ClassMethods#helper]
-      # instead when using +capture+.
+      # Note that the proxy is rendered under a different view context. This may cause
+      # incorrect behavior with capture methods. Consider using
+      # [helper](rdoc-ref:AbstractController::Helpers::ClassMethods#helper) instead
+      # when using `capture`.
       def helpers
         @helper_proxy ||= begin
           proxy = ActionView::Base.empty
@@ -93,21 +99,23 @@ module ActionController
         end
       end
 
-      # Override modules_for_helpers to accept +:all+ as argument, which loads
-      # all helpers in helpers_path.
+      # Override modules_for_helpers to accept `:all` as argument, which loads all
+      # helpers in helpers_path.
+      #
+      # #### Parameters
+      # *   `args` - A list of helpers
+      #
       #
-      # ==== Parameters
-      # * <tt>args</tt> - A list of helpers
+      # #### Returns
+      # *   `array` - A normalized list of modules for the list of helpers provided.
       #
-      # ==== Returns
-      # * <tt>array</tt> - A normalized list of modules for the list of helpers provided.
       def modules_for_helpers(args)
         args += all_application_helpers if args.delete(:all)
         super(args)
       end
 
       private
-        # Extract helper names from files in <tt>app/helpers/**/*_helper.rb</tt>
+        # Extract helper names from files in `app/helpers/***/**_helper.rb`
         def all_application_helpers
           all_helpers_from_path(helpers_path)
         end