Merge pull request #22785 from timrogers/master

Improve documentation for `config.ssl_options`

2 files changed, 16 insertions, 14 deletions

diff --git a/actionpack/lib/action_dispatch/middleware/ssl.rb b/actionpack/lib/action_dispatch/middleware/ssl.rb
index 47f475559a..8f8f1bab8b 100644
--- a/actionpack/lib/action_dispatch/middleware/ssl.rb
+++ b/actionpack/lib/action_dispatch/middleware/ssl.rb
@@ -1,19 +1,21 @@
 module ActionDispatch
-  # This middleware is added to the stack when `config.force_ssl = true`.
-  # It does three jobs to enforce secure HTTP requests:
+  # This middleware is added to the stack when `config.force_ssl = true`, and is passed
+  # the options set in `config.ssl_options`. It does three jobs to enforce secure HTTP
+  # requests:
   #
-  #   1. TLS redirect. http:// requests are permanently redirected to https://
-  #      with the same URL host, path, etc. Pass `:host` and/or `:port` to
-  #      modify the destination URL. This is always enabled.
+  #   1. TLS redirect: Permanently redirects http:// requests to https://
+  #      with the same URL host, path, etc. This is always enabled. Set
+  #      `config.ssl_options` to modify the destination URL
+  #      (e.g. `redirect: { host: "secure.widgets.com", port: 8080 }`)
   #
-  #   2. Secure cookies. Sets the `secure` flag on cookies to tell browsers they
+  #   2. Secure cookies: Sets the `secure` flag on cookies to tell browsers they
   #      mustn't be sent along with http:// requests. This is always enabled.
   #
-  #   3. HTTP Strict Transport Security (HSTS). Tells the browser to remember
+  #   3. HTTP Strict Transport Security (HSTS): Tells the browser to remember
   #      this site as TLS-only and automatically redirect non-TLS requests.
   #      Enabled by default. Pass `hsts: false` to disable.
   #
-  # Configure HSTS with `hsts: { … }`:
+  # Set `config.ssl_options` with `hsts: { … }` to configure HSTS:
   #   * `expires`: How long, in seconds, these settings will stick. Defaults to
   #     `180.days` (recommended). The minimum required to qualify for browser
   #     preload lists is `18.weeks`.
@@ -26,10 +28,10 @@ module ActionDispatch
   #     gap, browser vendors include a baked-in list of HSTS-enabled sites.
   #     Go to https://hstspreload.appspot.com to submit your site for inclusion.
   #
-  # Disabling HSTS: To turn off HSTS, omitting the header is not enough.
-  # Browsers will remember the original HSTS directive until it expires.
-  # Instead, use the header to tell browsers to expire HSTS immediately.
-  # Setting `hsts: false` is a shortcut for `hsts: { expires: 0 }`.
+  # To turn off HSTS, omitting the header is not enough. Browsers will remember the
+  # original HSTS directive until it expires. Instead, use the header to tell browsers to
+  # expire HSTS immediately. Setting `hsts: false` is a shortcut for
+  # `hsts: { expires: 0 }`.
   class SSL
     # Default to 180 days, the low end for https://www.ssllabs.com/ssltest/
     # and greater than the 18-week requirement for browser preload lists.
diff --git a/guides/source/configuring.md b/guides/source/configuring.md
index 47acff7c3f..81e406ae2e 100644
--- a/guides/source/configuring.md
+++ b/guides/source/configuring.md
@@ -104,7 +104,7 @@ application. Accepts a valid week day symbol (e.g. `:monday`).
 you don't want shown in the logs, such as passwords or credit card
 numbers. New applications filter out passwords by adding the following `config.filter_parameters+=[:password]` in `config/initializers/filter_parameter_logging.rb`.
 
-* `config.force_ssl` forces all requests to be under HTTPS protocol by using `ActionDispatch::SSL` middleware.
+* `config.force_ssl` forces all requests to be served over HTTPS by using the `ActionDispatch::SSL` middleware. This can be configured by setting `config.ssl_options` - see the [ActionDispatch::SSL documentation](http://edgeapi.rubyonrails.org/classes/ActionDispatch/SSL.html) for details.
 
 * `config.log_formatter` defines the formatter of the Rails logger. This option defaults to an instance of `ActiveSupport::Logger::SimpleFormatter` for all modes except production, where it defaults to `Logger::Formatter`.
 
@@ -198,7 +198,7 @@ The full set of methods that can be used in this block are as follows:
 
 Every Rails application comes with a standard set of middleware which it uses in this order in the development environment:
 
-* `ActionDispatch::SSL` forces every request to be under HTTPS protocol. Will be available if `config.force_ssl` is set to `true`. Options passed to this can be configured by using `config.ssl_options`.
+* `ActionDispatch::SSL` forces every request to be served using HTTPS. Enabled if `config.force_ssl` is set to `true`. Options passed to this can be configured by setting `config.ssl_options`.
 * `ActionDispatch::Static` is used to serve static assets. Disabled if `config.public_file_server.enabled` is `false`. Set `config.public_file_server.index_name` if you need to serve a static directory index file that is not named `index`. For example, to serve `main.html` instead of `index.html` for directory requests, set `config.public_file_server.index_name` to `"main"`.
 * `Rack::Lock` wraps the app in mutex so it can only be called by a single thread at a time. Only enabled when `config.cache_classes` is `false`.
 * `ActiveSupport::Cache::Strategy::LocalCache` serves as a basic memory backed cache. This cache is not thread safe and is intended only for serving as a temporary memory cache for a single thread.