Merge pull request #5367 from carlosantoniodasilva/middleware-api

Change api_only to http_only and add MiddlewareStackProxy docs

2 files changed, 48 insertions, 11 deletions

diff --git a/railties/lib/rails/application.rb b/railties/lib/rails/application.rb
index 10fa63c303..3191fe68a7 100644
--- a/railties/lib/rails/application.rb
+++ b/railties/lib/rails/application.rb
@@ -239,7 +239,7 @@ module Rails
 
         middleware.use ::Rack::Lock unless config.allow_concurrency
         middleware.use ::Rack::Runtime
-        middleware.use ::Rack::MethodOverride unless config.middleware.api_only?
+        middleware.use ::Rack::MethodOverride unless config.middleware.http_only?
         middleware.use ::ActionDispatch::RequestId
         middleware.use ::Rails::Rack::Logger, config.log_tags # must come after Rack::MethodOverride to properly log overridden methods
         middleware.use ::ActionDispatch::ShowExceptions, config.exceptions_app || ActionDispatch::PublicExceptions.new(Rails.public_path)
@@ -252,9 +252,9 @@ module Rails
         end
 
         middleware.use ::ActionDispatch::Callbacks
-        middleware.use ::ActionDispatch::Cookies unless config.middleware.api_only?
+        middleware.use ::ActionDispatch::Cookies unless config.middleware.http_only?
 
-        if !config.middleware.api_only? && config.session_store
+        if !config.middleware.http_only? && config.session_store
           if config.force_ssl && !config.session_options.key?(:secure)
             config.session_options[:secure] = true
           end
@@ -267,7 +267,7 @@ module Rails
         middleware.use ::Rack::ConditionalGet
         middleware.use ::Rack::ETag, "no-cache"
 
-        if !config.middleware.api_only? && config.action_dispatch.best_standards_support
+        if !config.middleware.http_only? && config.action_dispatch.best_standards_support
           middleware.use ::ActionDispatch::BestStandardsSupport, config.action_dispatch.best_standards_support
         end
       end
diff --git a/railties/lib/rails/configuration.rb b/railties/lib/rails/configuration.rb
index 0efa21d82c..d8185bcb34 100644
--- a/railties/lib/rails/configuration.rb
+++ b/railties/lib/rails/configuration.rb
@@ -6,17 +6,54 @@ require 'rails/rack'
 
 module Rails
   module Configuration
-    class MiddlewareStackProxy #:nodoc:
+    # MiddlewareStackProxy is a proxy for the Rails middleware stack that allows
+    # you to configure middlewares in your application. It works basically as a
+    # command recorder, saving each command to be applied after initialization
+    # over the default middleware stack, so you can add, swap, or remove any
+    # middleware in Rails.
+    #
+    # You can add your own middlewares by using the +config.middleware.use+ method:
+    #
+    #     config.middleware.use Magical::Unicorns
+    #
+    # This will put the +Magical::Unicorns+ middleware on the end of the stack.
+    # You can use +insert_before+ if you wish to add a middleware before another:
+    #
+    #     config.middleware.insert_before ActionDispatch::Head, Magical::Unicorns
+    #
+    # There's also +insert_after+ which will insert a middleware after another:
+    #
+    #     config.middleware.insert_after ActionDispatch::Head, Magical::Unicorns
+    #
+    # Middlewares can also be completely swapped out and replaced with others:
+    #
+    #     config.middleware.swap ActionDispatch::BestStandardsSupport, Magical::Unicorns
+    #
+    # And finally they can also be removed from the stack completely:
+    #
+    #     config.middleware.delete ActionDispatch::BestStandardsSupport
+    #
+    # In addition to these methods to handle the stack, if your application is
+    # going to be used as an API endpoint only, the middleware stack can be
+    # configured like this:
+    #
+    #     config.middleware.http_only!
+    #
+    # By doing this, Rails will create a smaller middleware stack, by not adding
+    # some middlewares that are usually useful for browser access only, such as
+    # Cookies, Session and Flash, BestStandardsSupport, and MethodOverride. You
+    # can always add any of them later manually if you want.
+    class MiddlewareStackProxy
       def initialize
         @operations = []
-        @api_only   = false
+        @http_only  = false
       end
 
-      attr_reader :api_only
-      alias       :api_only? :api_only
+      attr_reader :http_only
+      alias       :http_only? :http_only
 
-      def api_only!
-        @api_only = true
+      def http_only!
+        @http_only = true
       end
 
       def insert_before(*args, &block)
@@ -41,7 +78,7 @@ module Rails
         @operations << [:delete, args, block]
       end
 
-      def merge_into(other)
+      def merge_into(other) #:nodoc:
         @operations.each do |operation, args, block|
           other.send(operation, *args, &block)
         end