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.
 

src/cowboy_rest.erl

@@ -180,6 +180,13 @@
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([previously_existed/2]).
 
+-callback rate_limited(Req, State)
+	-> {{true, non_neg_integer() | calendar:datetime()} | false, Req, State}
+	| {stop, Req, State}
+	| {switch_handler(), Req, State}
+	when Req::cowboy_req:req(), State::any().
+-optional_callbacks([rate_limited/2]).
+
 -callback resource_exists(Req, State)
 	-> {boolean(), Req, State}
 	| {stop, Req, State}
@@ -363,7 +370,28 @@ is_authorized(Req, State) ->
 	end.
 
 forbidden(Req, State) ->
-	expect(Req, State, forbidden, false, fun valid_content_headers/2, 403).
+	expect(Req, State, forbidden, false, fun rate_limited/2, 403).
+
+rate_limited(Req, State) ->
+	case call(Req, State, rate_limited) of
+		no_call ->
+			valid_content_headers(Req, State);
+		{stop, Req2, HandlerState} ->
+			terminate(Req2, State#state{handler_state=HandlerState});
+		{Switch, Req2, HandlerState} when element(1, Switch) =:= switch_handler ->
+			switch_handler(Switch, Req2, HandlerState);
+		{false, Req2, HandlerState} ->
+			valid_content_headers(Req2, State#state{handler_state=HandlerState});
+		{{true, RetryAfter0}, Req2, HandlerState} ->
+			RetryAfter = if
+				is_integer(RetryAfter0), RetryAfter0 >= 0 ->
+					integer_to_binary(RetryAfter0);
+				is_tuple(RetryAfter0) ->
+					cowboy_clock:rfc1123(RetryAfter0)
+			end,
+			Req3 = cowboy_req:set_resp_header(<<"retry-after">>, RetryAfter, Req2),
+			respond(Req3, State#state{handler_state=HandlerState}, 429)
+	end.
 
 valid_content_headers(Req, State) ->
 	expect(Req, State, valid_content_headers, true,

test/handlers/rate_limited_h.erl

@@ -0,0 +1,24 @@
+%% This module does rate limiting based on the query string value.
+
+-module(rate_limited_h).
+
+-export([init/2]).
+-export([rate_limited/2]).
+-export([content_types_provided/2]).
+-export([get_text_plain/2]).
+
+init(Req, State) ->
+	{cowboy_rest, Req, State}.
+
+rate_limited(Req=#{qs := <<"false">>}, State) ->
+	{false, Req, State};
+rate_limited(Req=#{qs := <<"true-date">>}, State) ->
+	{{true, {{2222, 2, 22}, {11, 11, 11}}}, Req, State};
+rate_limited(Req=#{qs := <<"true">>}, State) ->
+	{{true, 3600}, Req, State}.
+
+content_types_provided(Req, State) ->
+	{[{{<<"text">>, <<"plain">>, []}, get_text_plain}], Req, State}.
+
+get_text_plain(Req, State) ->
+	{<<"This is REST!">>, Req, State}.

test/rest_handler_SUITE.erl

@@ -48,6 +48,7 @@ init_dispatch(_) ->
 		{"/charset_in_content_types_provided_implicit_no_callback",
 			charset_in_content_types_provided_implicit_no_callback_h, []},
 		{"/provide_callback_missing", provide_callback_missing_h, []},
+		{"/rate_limited", rate_limited_h, []},
 		{"/switch_handler", switch_handler_h, run},
 		{"/switch_handler_opts", switch_handler_h, hibernate}
 	]}]).
@@ -287,6 +288,31 @@ provide_callback_missing(Config) ->
 	{response, fin, 500, _} = gun:await(ConnPid, Ref),
 	ok.
 
+rate_limited(Config) ->
+	doc("A 429 response must be sent when the rate_limited callback returns true. "
+		"The retry-after header is specified as an integer."),
+	ConnPid = gun_open(Config),
+	Ref = gun:get(ConnPid, "/rate_limited?true", [{<<"accept-encoding">>, <<"gzip">>}]),
+	{response, fin, 429, Headers} = gun:await(ConnPid, Ref),
+	{_, <<"3600">>} = lists:keyfind(<<"retry-after">>, 1, Headers),
+	ok.
+
+rate_limited_datetime(Config) ->
+	doc("A 429 response must be sent when the rate_limited callback returns true. "
+		"The retry-after header is specified as a date/time tuple."),
+	ConnPid = gun_open(Config),
+	Ref = gun:get(ConnPid, "/rate_limited?true-date", [{<<"accept-encoding">>, <<"gzip">>}]),
+	{response, fin, 429, Headers} = gun:await(ConnPid, Ref),
+	{_, <<"Fri, 22 Feb 2222 11:11:11 GMT">>} = lists:keyfind(<<"retry-after">>, 1, Headers),
+	ok.
+
+rate_not_limited(Config) ->
+	doc("A success response must be sent when the rate_limited callback returns false."),
+	ConnPid = gun_open(Config),
+	Ref = gun:get(ConnPid, "/rate_limited?false", [{<<"accept-encoding">>, <<"gzip">>}]),
+	{response, nofin, 200, _} = gun:await(ConnPid, Ref),
+	ok.
+
 switch_handler(Config) ->
 	doc("Switch REST to loop handler for streaming the response body."),
 	ConnPid = gun_open(Config),