Add the rate_limited/2 REST callback

doc/src/guide/resource_design.asciidoc

@@ -122,6 +122,9 @@ Can access to a resource be forbidden regardless of access
 being authorized? A simple example of that is censorship
 of a resource. Implement the `forbidden` callback.
 
+Can access be rate-limited for authenticated users? Use the
+`rate_limited` callback.
+
 Are there any constraints on the length of the resource URI?
 For example, the URI may be used as a key in storage and may
 have a limit in length. Implement `uri_too_long`.

doc/src/guide/rest_handlers.asciidoc

@@ -84,6 +84,7 @@ if it is undefined, moving directly to the next step. Similarly,
 | multiple_choices       | `false`
 | options                | `ok`
 | previously_existed     | `false`
+| rate_limited           | `false`
 | resource_exists        | `true`
 | service_available      | `true`
 | uri_too_long           | `false`

doc/src/manual/cowboy_rest.asciidoc

@@ -603,6 +603,30 @@ release.
 
 // @todo Add a way to switch to loop handler for streaming the body.
 
+=== rate_limited
+
+[source,erlang]
+----
+rate_limited(Req, State) -> {Result, Req, State}
+
+Result     :: false | {true, RetryAfter}
+RetryAfter :: non_neg_integer() | calendar:datetime()
+Default  - false
+----
+
+Return whether the user is rate limited.
+
+This function can be used to temporarily restrict
+access to a resource when the user has issued too
+many requests.
+
+When the resource is rate limited the `RetryAfter`
+value will be sent in the retry-after header for the
+'429 Too Many Requests' response. It indicates when
+the resource will become available again and can be
+specified as a number of seconds in the future or a
+specific date/time.
+
 === resource_exists
 
 [source,erlang]
@@ -696,6 +720,7 @@ listed here, like the authorization header.
 
 == Changelog
 
+* *2.6*: The callback `rate_limited` was added.
 * *2.1*: The `switch_handler` return value was added.
 * *1.0*: Behavior introduced.