RateLimiting: raise ActionController::TooManyRequests error

Prior to this commit, the default behavior for exceeding a rate limit
involved responding with a status of [429 Too many requests][]. The only
indication that a rate limit was exceeded was the `429` code.

This commit changes the default behavior from a `head :too_many_requests`
call to instead raise a new `ActionController::TooManyRequests` error.
This change adheres more closely to precedent established by other
status codes like `ActionController::BadRequest` to a `:bad_request`
(`400 Bad Request`) status, or `ActiveRecord::RecordNotFound` to a
`:not_found` (`404 Not Found`) status.

Application-side controllers can be configured to `rescue_from` that
exception, or they can rely on a new
`ActionController::TooManyRequests`-to-`429 Too many requests` status
mapping entry in the `ActionDispatch/Middleware/ExceptionWrapper`
error-to-status mapping.

[429 Too many requests]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/429

Author: seanpdoyle

actionpack/CHANGELOG.md

@@ -1,3 +1,10 @@
+*   Raise `ActionController::TooManyRequests` error from `ActionController::RateLimiting`
+
+    Requests that exceed the rate limit raise an `ActionController::TooManyRequests` error.
+    By default, Action Dispatch rescues the error and responds with a `429 Too Many Requests` status.
+
+    *Sean Doyle*
+
 *   Add .md/.markdown as Markdown extensions and add a default `markdown:` renderer:
 
     ```ruby

actionpack/lib/action_controller/metal/exceptions.rb

@@ -103,4 +103,9 @@ def initialize(message, controller, action_name)
       super(message)
     end
   end
+
+  # Raised when a Rate Limit is exceeded by too many requests within a period of
+  # time.
+  class TooManyRequests < ActionControllerError
+  end
 end

actionpack/lib/action_controller/metal/rate_limiting.rb

@@ -22,8 +22,9 @@ module ClassMethods
       # share rate limits across multiple controllers, you can provide your own scope,
       # by passing value in the `scope:` parameter.
       #
-      # Requests that exceed the rate limit are refused with a `429 Too Many Requests`
-      # response. You can specialize this by passing a callable in the `with:`
+      # Requests that exceed the rate limit will raise an `ActionController::TooManyRequests`
+      # error. By default, Action Dispatch will rescue from the error and refuse the request
+      # with a `429 Too Many Requests` response. You can specialize this by passing a callable in the `with:`
       # parameter. It's evaluated within the context of the controller processing the
       # request.
       #
@@ -57,7 +58,7 @@ module ClassMethods
       #       rate_limit to: 3, within: 2.seconds, name: "short-term"
       #       rate_limit to: 10, within: 5.minutes, name: "long-term"
       #     end
-      def rate_limit(to:, within:, by: -> { request.remote_ip }, with: -> { head :too_many_requests }, store: cache_store, name: nil, scope: nil, **options)
+      def rate_limit(to:, within:, by: -> { request.remote_ip }, with: -> { raise TooManyRequests }, store: cache_store, name: nil, scope: nil, **options)
         before_action -> { rate_limiting(to: to, within: within, by: by, with: with, store: store, name: name, scope: scope || controller_path) }, **options
       end
     end

actionpack/lib/action_dispatch/middleware/exception_wrapper.rb

@@ -23,6 +23,7 @@ class ExceptionWrapper
       "ActionDispatch::Http::Parameters::ParseError"       => :bad_request,
       "ActionController::BadRequest"                       => :bad_request,
       "ActionController::ParameterMissing"                 => :bad_request,
+      "ActionController::TooManyRequests"                  => :too_many_requests,
       "Rack::QueryParser::ParameterTypeError"              => :bad_request,
       "Rack::QueryParser::InvalidParameterError"           => :bad_request
     )

actionpack/test/controller/api/rate_limiting_test.rb

@@ -23,8 +23,9 @@ class ApiRateLimitingTest < ActionController::TestCase
     get :limited_to_two
     assert_response :ok
 
-    get :limited_to_two
-    assert_response :too_many_requests
+    assert_raises ActionController::TooManyRequests do
+      get :limited_to_two
+    end
   end
 
   test "limit resets after time" do

actionpack/test/controller/rate_limiting_test.rb

@@ -66,8 +66,9 @@ class RateLimitingTest < ActionController::TestCase
     get :limited
     assert_response :ok
 
-    get :limited
-    assert_response :too_many_requests
+    assert_raises ActionController::TooManyRequests do
+      get :limited
+    end
   end
 
   test "notification on limit action" do
@@ -80,25 +81,27 @@ class RateLimitingTest < ActionController::TestCase
         within: 2.seconds,
         name: nil,
         by: request.remote_ip) do
-      get :limited
+      assert_raises ActionController::TooManyRequests do
+        get :limited
+      end
     end
   end
 
   test "multiple rate limits" do
+    freeze_time
     get :limited
     get :limited
     assert_response :ok
 
-    travel_to 3.seconds.from_now do
-      get :limited
-      get :limited
-      assert_response :ok
-    end
+    travel 3.seconds
+    get :limited
+    get :limited
+    assert_response :ok
 
-    travel_to 3.seconds.from_now do
-      get :limited
+    travel 3.seconds
+    get :limited
+    assert_raises ActionController::TooManyRequests do
       get :limited
-      assert_response :too_many_requests
     end
   end
 
@@ -140,13 +143,15 @@ class RateLimitingTest < ActionController::TestCase
 
     @controller = RateLimitedSharedTwoController.new
 
-    get :limited_shared_two
-    assert_response :too_many_requests
+    assert_raises ActionController::TooManyRequests do
+      get :limited_shared_two
+    end
 
     @controller = RateLimitedSharedOneController.new
 
-    get :limited_shared_one
-    assert_response :too_many_requests
+    assert_raises ActionController::TooManyRequests do
+      get :limited_shared_one
+    end
   ensure
     RateLimitedBaseController.cache_store.clear
   end
@@ -166,8 +171,9 @@ class RateLimitingTest < ActionController::TestCase
 
     @controller = RateLimitedSharedThreeController.new
 
-    get :limited_shared_three
-    assert_response :too_many_requests
+    assert_raises ActionController::TooManyRequests do
+      get :limited_shared_three
+    end
   ensure
     RateLimitedSharedController.cache_store.clear
   end

actionpack/test/dispatch/show_exceptions_test.rb

@@ -27,6 +27,8 @@ def call(env)
         rescue
           raise ActionView::Template::Error.new("template")
         end
+      when "/rate_limited"
+        raise ActionController::TooManyRequests.new
       else
         raise "puke!"
       end
@@ -41,6 +43,10 @@ def setup
     assert_raise RuntimeError do
       get "/", env: { "action_dispatch.show_exceptions" => :none }
     end
+
+    assert_raise ActionController::TooManyRequests do
+      get "/rate_limited", headers: { "action_dispatch.show_exceptions" => :none }
+    end
   end
 
   test "rescue with error page" do
@@ -67,6 +73,10 @@ def setup
     get "/invalid_mimetype", headers: { "Accept" => "text/html,*", "action_dispatch.show_exceptions" => :all }
     assert_response 406
     assert_equal "", body
+
+    get "/rate_limited", headers: { "action_dispatch.show_exceptions" => :all }
+    assert_response 429
+    assert_equal "", body
   end
 
   test "rescue with no body for HEAD requests" do