zf

cowboy_rest.erl (59826B)

---

 %% Copyright (c) 2011-2017, Loïc Hoguin <essen@ninenines.eu>
 %%
 %% Permission to use, copy, modify, and/or distribute this software for any
 %% purpose with or without fee is hereby granted, provided that the above
 %% copyright notice and this permission notice appear in all copies.
 %%
 %% THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 %% WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 %% MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 %% ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 %% WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
 %% Originally based on the Webmachine Diagram from Alan Dean and
 %% Justin Sheehy.
 -module(cowboy_rest).
 -behaviour(cowboy_sub_protocol).
 
 -export([upgrade/4]).
 -export([upgrade/5]).
 
 -type switch_handler() :: {switch_handler, module()}
 	| {switch_handler, module(), any()}.
 
 %% Common handler callbacks.
 
 -callback init(Req, any())
 	-> {ok | module(), Req, any()}
 	| {module(), Req, any(), any()}
 	when Req::cowboy_req:req().
 
 -callback terminate(any(), cowboy_req:req(), any()) -> ok.
 -optional_callbacks([terminate/3]).
 
 %% REST handler callbacks.
 
 -callback allowed_methods(Req, State)
 	-> {[binary()], Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([allowed_methods/2]).
 
 -callback allow_missing_post(Req, State)
 	-> {boolean(), Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([allow_missing_post/2]).
 
 -callback charsets_provided(Req, State)
 	-> {[binary()], Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([charsets_provided/2]).
 
 -callback content_types_accepted(Req, State)
 	-> {[{'*' | binary() | {binary(), binary(), '*' | [{binary(), binary()}]}, atom()}], Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([content_types_accepted/2]).
 
 -callback content_types_provided(Req, State)
 	-> {[{binary() | {binary(), binary(), '*' | [{binary(), binary()}]}, atom()}], Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([content_types_provided/2]).
 
 -callback delete_completed(Req, State)
 	-> {boolean(), Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([delete_completed/2]).
 
 -callback delete_resource(Req, State)
 	-> {boolean(), Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([delete_resource/2]).
 
 -callback expires(Req, State)
 	-> {calendar:datetime() | binary() | undefined, Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([expires/2]).
 
 -callback forbidden(Req, State)
 	-> {boolean(), Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([forbidden/2]).
 
 -callback generate_etag(Req, State)
 	-> {binary() | {weak | strong, binary()}, Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([generate_etag/2]).
 
 -callback is_authorized(Req, State)
 	-> {true | {false, iodata()}, Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([is_authorized/2]).
 
 -callback is_conflict(Req, State)
 	-> {boolean(), Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([is_conflict/2]).
 
 -callback known_methods(Req, State)
 	-> {[binary()], Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([known_methods/2]).
 
 -callback languages_provided(Req, State)
 	-> {[binary()], Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([languages_provided/2]).
 
 -callback last_modified(Req, State)
 	-> {calendar:datetime(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([last_modified/2]).
 
 -callback malformed_request(Req, State)
 	-> {boolean(), Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([malformed_request/2]).
 
 -callback moved_permanently(Req, State)
 	-> {{true, iodata()} | false, Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([moved_permanently/2]).
 
 -callback moved_temporarily(Req, State)
 	-> {{true, iodata()} | false, Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([moved_temporarily/2]).
 
 -callback multiple_choices(Req, State)
 	-> {boolean(), Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([multiple_choices/2]).
 
 -callback options(Req, State)
 	-> {ok, Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([options/2]).
 
 -callback previously_existed(Req, State)
 	-> {boolean(), Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([previously_existed/2]).
 
 -callback range_satisfiable(Req, State)
 	-> {boolean() | {false, non_neg_integer() | iodata()}, Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([range_satisfiable/2]).
 
 -callback ranges_provided(Req, State)
 	-> {[{binary(), atom()}], Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([ranges_provided/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}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([resource_exists/2]).
 
 -callback service_available(Req, State)
 	-> {boolean(), Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([service_available/2]).
 
 -callback uri_too_long(Req, State)
 	-> {boolean(), Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([uri_too_long/2]).
 
 -callback valid_content_headers(Req, State)
 	-> {boolean(), Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([valid_content_headers/2]).
 
 -callback valid_entity_length(Req, State)
 	-> {boolean(), Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([valid_entity_length/2]).
 
 -callback variances(Req, State)
 	-> {[binary()], Req, State}
 	when Req::cowboy_req:req(), State::any().
 -optional_callbacks([variances/2]).
 
 %% End of REST callbacks. Whew!
 
 -record(state, {
 	method = undefined :: binary(),
 
 	%% Handler.
 	handler :: atom(),
 	handler_state :: any(),
 
 	%% Allowed methods. Only used for OPTIONS requests.
 	allowed_methods :: [binary()] | undefined,
 
 	%% Media type.
 	content_types_p = [] ::
 		[{binary() | {binary(), binary(), [{binary(), binary()}] | '*'},
 			atom()}],
 	content_type_a :: undefined
 		| {binary() | {binary(), binary(), [{binary(), binary()}] | '*'},
 			atom()},
 
 	%% Language.
 	languages_p = [] :: [binary()],
 	language_a :: undefined | binary(),
 
 	%% Charset.
 	charsets_p = undefined :: undefined | [binary()],
 	charset_a :: undefined | binary(),
 
 	%% Range units.
 	ranges_a = [] :: [{binary(), atom()}],
 
 	%% Whether the resource exists.
 	exists = false :: boolean(),
 
 	%% Cached resource calls.
 	etag :: undefined | no_call | {strong | weak, binary()},
 	last_modified :: undefined | no_call | calendar:datetime(),
 	expires :: undefined | no_call | calendar:datetime() | binary()
 }).
 
 -spec upgrade(Req, Env, module(), any())
 	-> {ok, Req, Env} when Req::cowboy_req:req(), Env::cowboy_middleware:env().
 upgrade(Req0, Env, Handler, HandlerState0) ->
 	Method = cowboy_req:method(Req0),
 	case service_available(Req0, #state{method=Method,
 			handler=Handler, handler_state=HandlerState0}) of
 		{ok, Req, Result} ->
 			{ok, Req, Env#{result => Result}};
 		{Mod, Req, HandlerState} ->
 			Mod:upgrade(Req, Env, Handler, HandlerState);
 		{Mod, Req, HandlerState, Opts} ->
 			Mod:upgrade(Req, Env, Handler, HandlerState, Opts)
 	end.
 
 -spec upgrade(Req, Env, module(), any(), any())
 	-> {ok, Req, Env} when Req::cowboy_req:req(), Env::cowboy_middleware:env().
 %% cowboy_rest takes no options.
 upgrade(Req, Env, Handler, HandlerState, _Opts) ->
 	upgrade(Req, Env, Handler, HandlerState).
 
 service_available(Req, State) ->
 	expect(Req, State, service_available, true, fun known_methods/2, 503).
 
 %% known_methods/2 should return a list of binary methods.
 known_methods(Req, State=#state{method=Method}) ->
 	case call(Req, State, known_methods) of
 		no_call when Method =:= <<"HEAD">>; Method =:= <<"GET">>;
 				Method =:= <<"POST">>; Method =:= <<"PUT">>;
 				Method =:= <<"PATCH">>; Method =:= <<"DELETE">>;
 				Method =:= <<"OPTIONS">> ->
 			next(Req, State, fun uri_too_long/2);
 		no_call ->
 			next(Req, State, 501);
 		{stop, Req2, State2} ->
 			terminate(Req2, State2);
 		{Switch, Req2, State2} when element(1, Switch) =:= switch_handler ->
 			switch_handler(Switch, Req2, State2);
 		{List, Req2, State2} ->
 			case lists:member(Method, List) of
 				true -> next(Req2, State2, fun uri_too_long/2);
 				false -> next(Req2, State2, 501)
 			end
 	end.
 
 uri_too_long(Req, State) ->
 	expect(Req, State, uri_too_long, false, fun allowed_methods/2, 414).
 
 %% allowed_methods/2 should return a list of binary methods.
 allowed_methods(Req, State=#state{method=Method}) ->
 	case call(Req, State, allowed_methods) of
 		no_call when Method =:= <<"HEAD">>; Method =:= <<"GET">> ->
 			next(Req, State, fun malformed_request/2);
 		no_call when Method =:= <<"OPTIONS">> ->
 			next(Req, State#state{allowed_methods=
 				[<<"HEAD">>, <<"GET">>, <<"OPTIONS">>]},
 				fun malformed_request/2);
 		no_call ->
 			method_not_allowed(Req, State,
 				[<<"HEAD">>, <<"GET">>, <<"OPTIONS">>]);
 		{stop, Req2, State2} ->
 			terminate(Req2, State2);
 		{Switch, Req2, State2} when element(1, Switch) =:= switch_handler ->
 			switch_handler(Switch, Req2, State2);
 		{List, Req2, State2} ->
 			case lists:member(Method, List) of
 				true when Method =:= <<"OPTIONS">> ->
 					next(Req2, State2#state{allowed_methods=List},
 						fun malformed_request/2);
 				true ->
 					next(Req2, State2, fun malformed_request/2);
 				false ->
 					method_not_allowed(Req2, State2, List)
 			end
 	end.
 
 method_not_allowed(Req, State, []) ->
 	Req2 = cowboy_req:set_resp_header(<<"allow">>, <<>>, Req),
 	respond(Req2, State, 405);
 method_not_allowed(Req, State, Methods) ->
 	<< ", ", Allow/binary >> = << << ", ", M/binary >> || M <- Methods >>,
 	Req2 = cowboy_req:set_resp_header(<<"allow">>, Allow, Req),
 	respond(Req2, State, 405).
 
 malformed_request(Req, State) ->
 	expect(Req, State, malformed_request, false, fun is_authorized/2, 400).
 
 %% is_authorized/2 should return true or {false, WwwAuthenticateHeader}.
 is_authorized(Req, State) ->
 	case call(Req, State, is_authorized) of
 		no_call ->
 			forbidden(Req, State);
 		{stop, Req2, State2} ->
 			terminate(Req2, State2);
 		{Switch, Req2, State2} when element(1, Switch) =:= switch_handler ->
 			switch_handler(Switch, Req2, State2);
 		{true, Req2, State2} ->
 			forbidden(Req2, State2);
 		{{false, AuthHead}, Req2, State2} ->
 			Req3 = cowboy_req:set_resp_header(
 				<<"www-authenticate">>, AuthHead, Req2),
 			respond(Req3, State2, 401)
 	end.
 
 forbidden(Req, State) ->
 	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, State2} ->
 			terminate(Req2, State2);
 		{Switch, Req2, State2} when element(1, Switch) =:= switch_handler ->
 			switch_handler(Switch, Req2, State2);
 		{false, Req2, State2} ->
 			valid_content_headers(Req2, State2);
 		{{true, RetryAfter0}, Req2, State2} ->
 			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, State2, 429)
 	end.
 
 valid_content_headers(Req, State) ->
 	expect(Req, State, valid_content_headers, true,
 		fun valid_entity_length/2, 501).
 
 valid_entity_length(Req, State) ->
 	expect(Req, State, valid_entity_length, true, fun options/2, 413).
 
 %% If you need to add additional headers to the response at this point,
 %% you should do it directly in the options/2 call using set_resp_headers.
 options(Req, State=#state{allowed_methods=Methods, method= <<"OPTIONS">>}) ->
 	case call(Req, State, options) of
 		no_call when Methods =:= [] ->
 			Req2 = cowboy_req:set_resp_header(<<"allow">>, <<>>, Req),
 			respond(Req2, State, 200);
 		no_call ->
 			<< ", ", Allow/binary >>
 				= << << ", ", M/binary >> || M <- Methods >>,
 			Req2 = cowboy_req:set_resp_header(<<"allow">>, Allow, Req),
 			respond(Req2, State, 200);
 		{stop, Req2, State2} ->
 			terminate(Req2, State2);
 		{Switch, Req2, State2} when element(1, Switch) =:= switch_handler ->
 			switch_handler(Switch, Req2, State2);
 		{ok, Req2, State2} ->
 			respond(Req2, State2, 200)
 	end;
 options(Req, State) ->
 	content_types_provided(Req, State).
 
 %% content_types_provided/2 should return a list of content types and their
 %% associated callback function as a tuple: {{Type, SubType, Params}, Fun}.
 %% Type and SubType are the media type as binary. Params is a list of
 %% Key/Value tuple, with Key and Value a binary. Fun is the name of the
 %% callback that will be used to return the content of the response. It is
 %% given as an atom.
 %%
 %% An example of such return value would be:
 %%    {{<<"text">>, <<"html">>, []}, to_html}
 %%
 %% Note that it is also possible to return a binary content type that will
 %% then be parsed by Cowboy. However note that while this may make your
 %% resources a little more readable, this is a lot less efficient.
 %%
 %% An example of such return value would be:
 %%    {<<"text/html">>, to_html}
 content_types_provided(Req, State) ->
 	case call(Req, State, content_types_provided) of
 		no_call ->
 			State2 = State#state{
 				content_types_p=[{{<<"text">>, <<"html">>, '*'}, to_html}]},
 			try cowboy_req:parse_header(<<"accept">>, Req) of
 				undefined ->
 					languages_provided(
 						Req#{media_type => {<<"text">>, <<"html">>, []}},
 						State2#state{content_type_a={{<<"text">>, <<"html">>, []}, to_html}});
 				Accept ->
 					choose_media_type(Req, State2, prioritize_accept(Accept))
 			catch _:_ ->
 				respond(Req, State2, 400)
 			end;
 		{stop, Req2, State2} ->
 			terminate(Req2, State2);
 		{Switch, Req2, State2} when element(1, Switch) =:= switch_handler ->
 			switch_handler(Switch, Req2, State2);
 		{[], Req2, State2} ->
 			not_acceptable(Req2, State2);
 		{CTP, Req2, State2} ->
 			CTP2 = [normalize_content_types(P) || P <- CTP],
 			State3 = State2#state{content_types_p=CTP2},
 			try cowboy_req:parse_header(<<"accept">>, Req2) of
 				undefined ->
 					{PMT0, _Fun} = HeadCTP = hd(CTP2),
 					%% We replace the wildcard by an empty list of parameters.
 					PMT = case PMT0 of
 						{Type, SubType, '*'} -> {Type, SubType, []};
 						_ -> PMT0
 					end,
 					languages_provided(
 						Req2#{media_type => PMT},
 						State3#state{content_type_a=HeadCTP});
 				Accept ->
 					choose_media_type(Req2, State3, prioritize_accept(Accept))
 			catch _:_ ->
 				respond(Req2, State3, 400)
 			end
 	end.
 
 normalize_content_types({ContentType, Callback})
 		when is_binary(ContentType) ->
 	{cow_http_hd:parse_content_type(ContentType), Callback};
 normalize_content_types(Normalized) ->
 	Normalized.
 
 prioritize_accept(Accept) ->
 	lists:sort(
 		fun ({MediaTypeA, Quality, _AcceptParamsA},
 			 {MediaTypeB, Quality, _AcceptParamsB}) ->
 				%% Same quality, check precedence in more details.
 				prioritize_mediatype(MediaTypeA, MediaTypeB);
 			({_MediaTypeA, QualityA, _AcceptParamsA},
 			 {_MediaTypeB, QualityB, _AcceptParamsB}) ->
 				%% Just compare the quality.
 				QualityA > QualityB
 		end, Accept).
 
 %% Media ranges can be overridden by more specific media ranges or
 %% specific media types. If more than one media range applies to a given
 %% type, the most specific reference has precedence.
 %%
 %% We always choose B over A when we can't decide between the two.
 prioritize_mediatype({TypeA, SubTypeA, ParamsA}, {TypeB, SubTypeB, ParamsB}) ->
 	case TypeB of
 		TypeA ->
 			case SubTypeB of
 				SubTypeA -> length(ParamsA) > length(ParamsB);
 				<<"*">> -> true;
 				_Any -> false
 			end;
 		<<"*">> -> true;
 		_Any -> false
 	end.
 
 %% Ignoring the rare AcceptParams. Not sure what should be done about them.
 choose_media_type(Req, State, []) ->
 	not_acceptable(Req, State);
 choose_media_type(Req, State=#state{content_types_p=CTP},
 		[MediaType|Tail]) ->
 	match_media_type(Req, State, Tail, CTP, MediaType).
 
 match_media_type(Req, State, Accept, [], _MediaType) ->
 	choose_media_type(Req, State, Accept);
 match_media_type(Req, State, Accept, CTP,
 		MediaType = {{<<"*">>, <<"*">>, _Params_A}, _QA, _APA}) ->
 	match_media_type_params(Req, State, Accept, CTP, MediaType);
 match_media_type(Req, State, Accept,
 			CTP = [{{Type, SubType_P, _PP}, _Fun}|_Tail],
 			MediaType = {{Type, SubType_A, _PA}, _QA, _APA})
 		when SubType_P =:= SubType_A; SubType_A =:= <<"*">> ->
 	match_media_type_params(Req, State, Accept, CTP, MediaType);
 match_media_type(Req, State, Accept, [_Any|Tail], MediaType) ->
 	match_media_type(Req, State, Accept, Tail, MediaType).
 
 match_media_type_params(Req, State, Accept,
 		[Provided = {{TP, STP, '*'}, _Fun}|Tail],
 		MediaType = {{TA, _STA, Params_A0}, _QA, _APA}) ->
 	case lists:keytake(<<"charset">>, 1, Params_A0) of
 		{value, {_, Charset}, Params_A} when TA =:= <<"text">> ->
 			%% When we match against a wildcard, the media type is text
 			%% and has a charset parameter, we call charsets_provided
 			%% and check that the charset is provided. If the callback
 			%% is not exported, we accept inconditionally but ignore
 			%% the given charset so as to not send a wrong value back.
 			case call(Req, State, charsets_provided) of
 				no_call ->
 					languages_provided(Req#{media_type => {TP, STP, Params_A0}},
 						State#state{content_type_a=Provided});
 				{stop, Req2, State2} ->
 					terminate(Req2, State2);
 				{Switch, Req2, State2} when element(1, Switch) =:= switch_handler ->
 					switch_handler(Switch, Req2, State2);
 				{CP, Req2, State2} ->
 					State3 = State2#state{charsets_p=CP},
 					case lists:member(Charset, CP) of
 						false ->
 							match_media_type(Req2, State3, Accept, Tail, MediaType);
 						true ->
 							languages_provided(Req2#{media_type => {TP, STP, Params_A}},
 								State3#state{content_type_a=Provided,
 									charset_a=Charset})
 					end
 			end;
 		_ ->
 			languages_provided(Req#{media_type => {TP, STP, Params_A0}},
 				State#state{content_type_a=Provided})
 	end;
 match_media_type_params(Req, State, Accept,
 		[Provided = {PMT = {TP, STP, Params_P0}, Fun}|Tail],
 		MediaType = {{_TA, _STA, Params_A}, _QA, _APA}) ->
 	case lists:sort(Params_P0) =:= lists:sort(Params_A) of
 		true when TP =:= <<"text">> ->
 			%% When a charset was provided explicitly in both the charset header
 			%% and the media types provided and the negotiation is successful,
 			%% we keep the charset and don't call charsets_provided. This only
 			%% applies to text media types, however.
 			{Charset, Params_P} = case lists:keytake(<<"charset">>, 1, Params_P0) of
 				false -> {undefined, Params_P0};
 				{value, {_, Charset0}, Params_P1} -> {Charset0, Params_P1}
 			end,
 			languages_provided(Req#{media_type => {TP, STP, Params_P}},
 				State#state{content_type_a={{TP, STP, Params_P}, Fun},
 					charset_a=Charset});
 		true ->
 			languages_provided(Req#{media_type => PMT},
 				State#state{content_type_a=Provided});
 		false ->
 			match_media_type(Req, State, Accept, Tail, MediaType)
 	end.
 
 %% languages_provided should return a list of binary values indicating
 %% which languages are accepted by the resource.
 %%
 %% @todo I suppose we should also ask the resource if it wants to
 %% set a language itself or if it wants it to be automatically chosen.
 languages_provided(Req, State) ->
 	case call(Req, State, languages_provided) of
 		no_call ->
 			charsets_provided(Req, State);
 		{stop, Req2, State2} ->
 			terminate(Req2, State2);
 		{Switch, Req2, State2} when element(1, Switch) =:= switch_handler ->
 			switch_handler(Switch, Req2, State2);
 		{[], Req2, State2} ->
 			not_acceptable(Req2, State2);
 		{LP, Req2, State2} ->
 			State3 = State2#state{languages_p=LP},
 			case cowboy_req:parse_header(<<"accept-language">>, Req2) of
 				undefined ->
 					set_language(Req2, State3#state{language_a=hd(LP)});
 				AcceptLanguage ->
 					AcceptLanguage2 = prioritize_languages(AcceptLanguage),
 					choose_language(Req2, State3, AcceptLanguage2)
 			end
 	end.
 
 %% A language-range matches a language-tag if it exactly equals the tag,
 %% or if it exactly equals a prefix of the tag such that the first tag
 %% character following the prefix is "-". The special range "*", if
 %% present in the Accept-Language field, matches every tag not matched
 %% by any other range present in the Accept-Language field.
 %%
 %% @todo The last sentence probably means we should always put '*'
 %% at the end of the list.
 prioritize_languages(AcceptLanguages) ->
 	lists:sort(
 		fun ({_TagA, QualityA}, {_TagB, QualityB}) ->
 			QualityA > QualityB
 		end, AcceptLanguages).
 
 choose_language(Req, State, []) ->
 	not_acceptable(Req, State);
 choose_language(Req, State=#state{languages_p=LP}, [Language|Tail]) ->
 	match_language(Req, State, Tail, LP, Language).
 
 match_language(Req, State, Accept, [], _Language) ->
 	choose_language(Req, State, Accept);
 match_language(Req, State, _Accept, [Provided|_Tail], {'*', _Quality}) ->
 	set_language(Req, State#state{language_a=Provided});
 match_language(Req, State, _Accept, [Provided|_Tail], {Provided, _Quality}) ->
 	set_language(Req, State#state{language_a=Provided});
 match_language(Req, State, Accept, [Provided|Tail],
 		Language = {Tag, _Quality}) ->
 	Length = byte_size(Tag),
 	case Provided of
 		<< Tag:Length/binary, $-, _Any/bits >> ->
 			set_language(Req, State#state{language_a=Provided});
 		_Any ->
 			match_language(Req, State, Accept, Tail, Language)
 	end.
 
 set_language(Req, State=#state{language_a=Language}) ->
 	Req2 = cowboy_req:set_resp_header(<<"content-language">>, Language, Req),
 	charsets_provided(Req2#{language => Language}, State).
 
 %% charsets_provided should return a list of binary values indicating
 %% which charsets are accepted by the resource.
 %%
 %% A charset may have been selected while negotiating the accept header.
 %% There's no need to select one again.
 charsets_provided(Req, State=#state{charset_a=Charset})
 		when Charset =/= undefined ->
 	set_content_type(Req, State);
 %% If charsets_p is defined, use it instead of calling charsets_provided
 %% again. We also call this clause during normal execution to avoid
 %% duplicating code.
 charsets_provided(Req, State=#state{charsets_p=[]}) ->
 	not_acceptable(Req, State);
 charsets_provided(Req, State=#state{charsets_p=CP})
 		when CP =/= undefined ->
 	case cowboy_req:parse_header(<<"accept-charset">>, Req) of
 		undefined ->
 			set_content_type(Req, State#state{charset_a=hd(CP)});
 		AcceptCharset0 ->
 			AcceptCharset = prioritize_charsets(AcceptCharset0),
 			choose_charset(Req, State, AcceptCharset)
 	end;
 charsets_provided(Req, State) ->
 	case call(Req, State, charsets_provided) of
 		no_call ->
 			set_content_type(Req, State);
 		{stop, Req2, State2} ->
 			terminate(Req2, State2);
 		{Switch, Req2, State2} when element(1, Switch) =:= switch_handler ->
 			switch_handler(Switch, Req2, State2);
 		{CP, Req2, State2} ->
 			charsets_provided(Req2, State2#state{charsets_p=CP})
 	end.
 
 prioritize_charsets(AcceptCharsets) ->
 	lists:sort(
 		fun ({_CharsetA, QualityA}, {_CharsetB, QualityB}) ->
 			QualityA > QualityB
 		end, AcceptCharsets).
 
 choose_charset(Req, State, []) ->
 	not_acceptable(Req, State);
 %% A q-value of 0 means not acceptable.
 choose_charset(Req, State, [{_, 0}|Tail]) ->
 	choose_charset(Req, State, Tail);
 choose_charset(Req, State=#state{charsets_p=CP}, [Charset|Tail]) ->
 	match_charset(Req, State, Tail, CP, Charset).
 
 match_charset(Req, State, Accept, [], _Charset) ->
 	choose_charset(Req, State, Accept);
 match_charset(Req, State, _Accept, [Provided|_], {<<"*">>, _}) ->
 	set_content_type(Req, State#state{charset_a=Provided});
 match_charset(Req, State, _Accept, [Provided|_], {Provided, _}) ->
 	set_content_type(Req, State#state{charset_a=Provided});
 match_charset(Req, State, Accept, [_|Tail], Charset) ->
 	match_charset(Req, State, Accept, Tail, Charset).
 
 set_content_type(Req, State=#state{
 		content_type_a={{Type, SubType, Params}, _Fun},
 		charset_a=Charset}) ->
 	ParamsBin = set_content_type_build_params(Params, []),
 	ContentType = [Type, <<"/">>, SubType, ParamsBin],
 	ContentType2 = case {Type, Charset} of
 		{<<"text">>, Charset} when Charset =/= undefined ->
 			[ContentType, <<"; charset=">>, Charset];
 		_ ->
 			ContentType
 	end,
 	Req2 = cowboy_req:set_resp_header(<<"content-type">>, ContentType2, Req),
 	encodings_provided(Req2#{charset => Charset}, State).
 
 set_content_type_build_params('*', []) ->
 	<<>>;
 set_content_type_build_params([], []) ->
 	<<>>;
 set_content_type_build_params([], Acc) ->
 	lists:reverse(Acc);
 set_content_type_build_params([{Attr, Value}|Tail], Acc) ->
 	set_content_type_build_params(Tail, [[Attr, <<"=">>, Value], <<";">>|Acc]).
 
 %% @todo Match for identity as we provide nothing else for now.
 %% @todo Don't forget to set the Content-Encoding header when we reply a body
 %% and the found encoding is something other than identity.
 encodings_provided(Req, State) ->
 	ranges_provided(Req, State).
 
 not_acceptable(Req, State) ->
 	respond(Req, State, 406).
 
 ranges_provided(Req, State) ->
 	case call(Req, State, ranges_provided) of
 		no_call ->
 			variances(Req, State);
 		{stop, Req2, State2} ->
 			terminate(Req2, State2);
 		{Switch, Req2, State2} when element(1, Switch) =:= switch_handler ->
 			switch_handler(Switch, Req2, State2);
 		{[], Req2, State2} ->
 			Req3 = cowboy_req:set_resp_header(<<"accept-ranges">>, <<"none">>, Req2),
 			variances(Req3, State2#state{ranges_a=[]});
 		{RP, Req2, State2} ->
 			<<", ", AcceptRanges/binary>> = <<<<", ", R/binary>> || {R, _} <- RP>>,
 			Req3 = cowboy_req:set_resp_header(<<"accept-ranges">>, AcceptRanges, Req2),
 			variances(Req3, State2#state{ranges_a=RP})
 	end.
 
 %% variances/2 should return a list of headers that will be added
 %% to the Vary response header. The Accept, Accept-Language,
 %% Accept-Charset and Accept-Encoding headers do not need to be
 %% specified.
 %%
 %% @todo Do Accept-Encoding too when we handle it.
 %% @todo Does the order matter?
 variances(Req, State=#state{content_types_p=CTP,
 		languages_p=LP, charsets_p=CP}) ->
 	Variances = case CTP of
 		[] -> [];
 		[_] -> [];
 		[_|_] -> [<<"accept">>]
 	end,
 	Variances2 = case LP of
 		[] -> Variances;
 		[_] -> Variances;
 		[_|_] -> [<<"accept-language">>|Variances]
 	end,
 	Variances3 = case CP of
 		undefined -> Variances2;
 		[] -> Variances2;
 		[_] -> Variances2;
 		[_|_] -> [<<"accept-charset">>|Variances2]
 	end,
 	try variances(Req, State, Variances3) of
 		{Variances4, Req2, State2} ->
 			case [[<<", ">>, V] || V <- Variances4] of
 				[] ->
 					resource_exists(Req2, State2);
 				[[<<", ">>, H]|Variances5] ->
 					Req3 = cowboy_req:set_resp_header(
 						<<"vary">>, [H|Variances5], Req2),
 					resource_exists(Req3, State2)
 			end
 	catch Class:Reason:Stacktrace ->
 		error_terminate(Req, State, Class, Reason, Stacktrace)
 	end.
 
 variances(Req, State, Variances) ->
 	case unsafe_call(Req, State, variances) of
 		no_call ->
 			{Variances, Req, State};
 		{HandlerVariances, Req2, State2} ->
 			{Variances ++ HandlerVariances, Req2, State2}
 	end.
 
 resource_exists(Req, State) ->
 	expect(Req, State, resource_exists, true,
 		fun if_match_exists/2, fun if_match_must_not_exist/2).
 
 if_match_exists(Req, State) ->
 	State2 = State#state{exists=true},
 	case cowboy_req:parse_header(<<"if-match">>, Req) of
 		undefined ->
 			if_unmodified_since_exists(Req, State2);
 		'*' ->
 			if_unmodified_since_exists(Req, State2);
 		ETagsList ->
 			if_match(Req, State2, ETagsList)
 	end.
 
 if_match(Req, State, EtagsList) ->
 	try generate_etag(Req, State) of
 		%% Strong Etag comparison: weak Etag never matches.
 		{{weak, _}, Req2, State2} ->
 			precondition_failed(Req2, State2);
 		{Etag, Req2, State2} ->
 			case lists:member(Etag, EtagsList) of
 				true -> if_none_match_exists(Req2, State2);
 				%% Etag may be `undefined' which cannot be a member.
 				false -> precondition_failed(Req2, State2)
 			end
 	catch Class:Reason:Stacktrace ->
 		error_terminate(Req, State, Class, Reason, Stacktrace)
 	end.
 
 if_match_must_not_exist(Req, State) ->
 	case cowboy_req:header(<<"if-match">>, Req) of
 		undefined -> is_put_to_missing_resource(Req, State);
 		_ -> precondition_failed(Req, State)
 	end.
 
 if_unmodified_since_exists(Req, State) ->
 	try cowboy_req:parse_header(<<"if-unmodified-since">>, Req) of
 		undefined ->
 			if_none_match_exists(Req, State);
 		IfUnmodifiedSince ->
 			if_unmodified_since(Req, State, IfUnmodifiedSince)
 	catch _:_ ->
 		if_none_match_exists(Req, State)
 	end.
 
 %% If LastModified is the atom 'no_call', we continue.
 if_unmodified_since(Req, State, IfUnmodifiedSince) ->
 	try last_modified(Req, State) of
 		{LastModified, Req2, State2} ->
 			case LastModified > IfUnmodifiedSince of
 				true -> precondition_failed(Req2, State2);
 				false -> if_none_match_exists(Req2, State2)
 			end
 	catch Class:Reason:Stacktrace ->
 		error_terminate(Req, State, Class, Reason, Stacktrace)
 	end.
 
 if_none_match_exists(Req, State) ->
 	case cowboy_req:parse_header(<<"if-none-match">>, Req) of
 		undefined ->
 			if_modified_since_exists(Req, State);
 		'*' ->
 			precondition_is_head_get(Req, State);
 		EtagsList ->
 			if_none_match(Req, State, EtagsList)
 	end.
 
 if_none_match(Req, State, EtagsList) ->
 	try generate_etag(Req, State) of
 		{Etag, Req2, State2} ->
 			case Etag of
 				undefined ->
 					precondition_failed(Req2, State2);
 				Etag ->
 					case is_weak_match(Etag, EtagsList) of
 						true -> precondition_is_head_get(Req2, State2);
 						false -> method(Req2, State2)
 					end
 			end
 	catch Class:Reason:Stacktrace ->
 		error_terminate(Req, State, Class, Reason, Stacktrace)
 	end.
 
 %% Weak Etag comparison: only check the opaque tag.
 is_weak_match(_, []) ->
 	false;
 is_weak_match({_, Tag}, [{_, Tag}|_]) ->
 	true;
 is_weak_match(Etag, [_|Tail]) ->
 	is_weak_match(Etag, Tail).
 
 precondition_is_head_get(Req, State=#state{method=Method})
 		when Method =:= <<"HEAD">>; Method =:= <<"GET">> ->
 	not_modified(Req, State);
 precondition_is_head_get(Req, State) ->
 	precondition_failed(Req, State).
 
 if_modified_since_exists(Req, State) ->
 	try cowboy_req:parse_header(<<"if-modified-since">>, Req) of
 		undefined ->
 			method(Req, State);
 		IfModifiedSince ->
 			if_modified_since_now(Req, State, IfModifiedSince)
 	catch _:_ ->
 		method(Req, State)
 	end.
 
 if_modified_since_now(Req, State, IfModifiedSince) ->
 	case IfModifiedSince > erlang:universaltime() of
 		true -> method(Req, State);
 		false -> if_modified_since(Req, State, IfModifiedSince)
 	end.
 
 if_modified_since(Req, State, IfModifiedSince) ->
 	try last_modified(Req, State) of
 		{undefined, Req2, State2} ->
 			method(Req2, State2);
 		{LastModified, Req2, State2} ->
 			case LastModified > IfModifiedSince of
 				true -> method(Req2, State2);
 				false -> not_modified(Req2, State2)
 			end
 	catch Class:Reason:Stacktrace ->
 		error_terminate(Req, State, Class, Reason, Stacktrace)
 	end.
 
 not_modified(Req, State) ->
 	Req2 = cowboy_req:delete_resp_header(<<"content-type">>, Req),
 	try set_resp_etag(Req2, State) of
 		{Req3, State2} ->
 			try set_resp_expires(Req3, State2) of
 				{Req4, State3} ->
 					respond(Req4, State3, 304)
 			catch Class:Reason:Stacktrace ->
 				error_terminate(Req, State2, Class, Reason, Stacktrace)
 			end
 	catch Class:Reason:Stacktrace ->
 		error_terminate(Req, State, Class, Reason, Stacktrace)
 	end.
 
 precondition_failed(Req, State) ->
 	respond(Req, State, 412).
 
 is_put_to_missing_resource(Req, State=#state{method= <<"PUT">>}) ->
 	moved_permanently(Req, State, fun is_conflict/2);
 is_put_to_missing_resource(Req, State) ->
 	previously_existed(Req, State).
 
 %% moved_permanently/2 should return either false or {true, Location}
 %% with Location the full new URI of the resource.
 moved_permanently(Req, State, OnFalse) ->
 	case call(Req, State, moved_permanently) of
 		{{true, Location}, Req2, State2} ->
 			Req3 = cowboy_req:set_resp_header(
 				<<"location">>, Location, Req2),
 			respond(Req3, State2, 301);
 		{false, Req2, State2} ->
 			OnFalse(Req2, State2);
 		{stop, Req2, State2} ->
 			terminate(Req2, State2);
 		{Switch, Req2, State2} when element(1, Switch) =:= switch_handler ->
 			switch_handler(Switch, Req2, State2);
 		no_call ->
 			OnFalse(Req, State)
 	end.
 
 previously_existed(Req, State) ->
 	expect(Req, State, previously_existed, false,
 		fun (R, S) -> is_post_to_missing_resource(R, S, 404) end,
 		fun (R, S) -> moved_permanently(R, S, fun moved_temporarily/2) end).
 
 %% moved_temporarily/2 should return either false or {true, Location}
 %% with Location the full new URI of the resource.
 moved_temporarily(Req, State) ->
 	case call(Req, State, moved_temporarily) of
 		{{true, Location}, Req2, State2} ->
 			Req3 = cowboy_req:set_resp_header(
 				<<"location">>, Location, Req2),
 			respond(Req3, State2, 307);
 		{false, Req2, State2} ->
 			is_post_to_missing_resource(Req2, State2, 410);
 		{stop, Req2, State2} ->
 			terminate(Req2, State2);
 		{Switch, Req2, State2} when element(1, Switch) =:= switch_handler ->
 			switch_handler(Switch, Req2, State2);
 		no_call ->
 			is_post_to_missing_resource(Req, State, 410)
 	end.
 
 is_post_to_missing_resource(Req, State=#state{method= <<"POST">>}, OnFalse) ->
 	allow_missing_post(Req, State, OnFalse);
 is_post_to_missing_resource(Req, State, OnFalse) ->
 	respond(Req, State, OnFalse).
 
 allow_missing_post(Req, State, OnFalse) ->
 	expect(Req, State, allow_missing_post, true, fun accept_resource/2, OnFalse).
 
 method(Req, State=#state{method= <<"DELETE">>}) ->
 	delete_resource(Req, State);
 method(Req, State=#state{method= <<"PUT">>}) ->
 	is_conflict(Req, State);
 method(Req, State=#state{method=Method})
 		when Method =:= <<"POST">>; Method =:= <<"PATCH">> ->
 	accept_resource(Req, State);
 method(Req, State=#state{method=Method})
 		when Method =:= <<"GET">>; Method =:= <<"HEAD">> ->
 	set_resp_body_etag(Req, State);
 method(Req, State) ->
 	multiple_choices(Req, State).
 
 %% delete_resource/2 should start deleting the resource and return.
 delete_resource(Req, State) ->
 	expect(Req, State, delete_resource, false, 500, fun delete_completed/2).
 
 %% delete_completed/2 indicates whether the resource has been deleted yet.
 delete_completed(Req, State) ->
 	expect(Req, State, delete_completed, true, fun has_resp_body/2, 202).
 
 is_conflict(Req, State) ->
 	expect(Req, State, is_conflict, false, fun accept_resource/2, 409).
 
 %% content_types_accepted should return a list of media types and their
 %% associated callback functions in the same format as content_types_provided.
 %%
 %% The callback will then be called and is expected to process the content
 %% pushed to the resource in the request body.
 %%
 %% content_types_accepted SHOULD return a different list
 %% for each HTTP method.
 accept_resource(Req, State) ->
 	case call(Req, State, content_types_accepted) of
 		no_call ->
 			respond(Req, State, 415);
 		{stop, Req2, State2} ->
 			terminate(Req2, State2);
 		{Switch, Req2, State2} when element(1, Switch) =:= switch_handler ->
 			switch_handler(Switch, Req2, State2);
 		{CTA, Req2, State2} ->
 			CTA2 = [normalize_content_types(P) || P <- CTA],
 			try cowboy_req:parse_header(<<"content-type">>, Req2) of
 				%% We do not match against the boundary parameter for multipart.
 				{Type = <<"multipart">>, SubType, Params} ->
 					ContentType = {Type, SubType, lists:keydelete(<<"boundary">>, 1, Params)},
 					choose_content_type(Req2, State2, ContentType, CTA2);
 				ContentType ->
 					choose_content_type(Req2, State2, ContentType, CTA2)
 			catch _:_ ->
 				respond(Req2, State2, 415)
 			end
 	end.
 
 %% The special content type '*' will always match. It can be used as a
 %% catch-all content type for accepting any kind of request content.
 %% Note that because it will always match, it should be the last of the
 %% list of content types, otherwise it'll shadow the ones following.
 choose_content_type(Req, State, _ContentType, []) ->
 	respond(Req, State, 415);
 choose_content_type(Req, State, ContentType, [{Accepted, Fun}|_Tail])
 		when Accepted =:= '*'; Accepted =:= ContentType ->
 	process_content_type(Req, State, Fun);
 %% The special parameter '*' will always match any kind of content type
 %% parameters.
 %% Note that because it will always match, it should be the last of the
 %% list for specific content type, otherwise it'll shadow the ones following.
 choose_content_type(Req, State, {Type, SubType, Param},
 		[{{Type, SubType, AcceptedParam}, Fun}|_Tail])
 		when AcceptedParam =:= '*'; AcceptedParam =:= Param ->
 	process_content_type(Req, State, Fun);
 choose_content_type(Req, State, ContentType, [_Any|Tail]) ->
 	choose_content_type(Req, State, ContentType, Tail).
 
 process_content_type(Req, State=#state{method=Method, exists=Exists}, Fun) ->
 	try case call(Req, State, Fun) of
 		{stop, Req2, State2} ->
 			terminate(Req2, State2);
 		{Switch, Req2, State2} when element(1, Switch) =:= switch_handler ->
 			switch_handler(Switch, Req2, State2);
 		{true, Req2, State2} when Exists ->
 			next(Req2, State2, fun has_resp_body/2);
 		{true, Req2, State2} ->
 			next(Req2, State2, fun maybe_created/2);
 		{false, Req2, State2} ->
 			respond(Req2, State2, 400);
 		{{created, ResURL}, Req2, State2} when Method =:= <<"POST">> ->
 			Req3 = cowboy_req:set_resp_header(
 				<<"location">>, ResURL, Req2),
 			respond(Req3, State2, 201);
 		{{see_other, ResURL}, Req2, State2} when Method =:= <<"POST">> ->
 			Req3 = cowboy_req:set_resp_header(
 				<<"location">>, ResURL, Req2),
 			respond(Req3, State2, 303);
 		{{true, ResURL}, Req2, State2} when Method =:= <<"POST">> ->
 			Req3 = cowboy_req:set_resp_header(
 				<<"location">>, ResURL, Req2),
 			if
 				Exists -> respond(Req3, State2, 303);
 				true -> respond(Req3, State2, 201)
 			end
 	end catch Class:Reason = {case_clause, no_call}:Stacktrace ->
 		error_terminate(Req, State, Class, Reason, Stacktrace)
 	end.
 
 %% If PUT was used then the resource has been created at the current URL.
 %% Otherwise, if a location header has been set then the resource has been
 %% created at a new URL. If not, send a 200 or 204 as expected from a
 %% POST or PATCH request.
 maybe_created(Req, State=#state{method= <<"PUT">>}) ->
 	respond(Req, State, 201);
 maybe_created(Req, State) ->
 	case cowboy_req:has_resp_header(<<"location">>, Req) of
 		true -> respond(Req, State, 201);
 		false -> has_resp_body(Req, State)
 	end.
 
 has_resp_body(Req, State) ->
 	case cowboy_req:has_resp_body(Req) of
 		true -> multiple_choices(Req, State);
 		false -> respond(Req, State, 204)
 	end.
 
 %% Set the Etag header if any for the response provided.
 set_resp_body_etag(Req, State) ->
 	try set_resp_etag(Req, State) of
 		{Req2, State2} ->
 			set_resp_body_last_modified(Req2, State2)
 	catch Class:Reason:Stacktrace ->
 		error_terminate(Req, State, Class, Reason, Stacktrace)
 	end.
 
 %% Set the Last-Modified header if any for the response provided.
 set_resp_body_last_modified(Req, State) ->
 	try last_modified(Req, State) of
 		{LastModified, Req2, State2} ->
 			case LastModified of
 				LastModified when is_atom(LastModified) ->
 					set_resp_body_expires(Req2, State2);
 				LastModified ->
 					LastModifiedBin = cowboy_clock:rfc1123(LastModified),
 					Req3 = cowboy_req:set_resp_header(
 						<<"last-modified">>, LastModifiedBin, Req2),
 					set_resp_body_expires(Req3, State2)
 			end
 	catch Class:Reason:Stacktrace ->
 		error_terminate(Req, State, Class, Reason, Stacktrace)
 	end.
 
 %% Set the Expires header if any for the response provided.
 set_resp_body_expires(Req, State) ->
 	try set_resp_expires(Req, State) of
 		{Req2, State2} ->
 			if_range(Req2, State2)
 	catch Class:Reason:Stacktrace ->
 		error_terminate(Req, State, Class, Reason, Stacktrace)
 	end.
 
 %% When both the if-range and range headers are set, we perform
 %% a strong comparison. If it fails, we send a full response.
 if_range(Req=#{headers := #{<<"if-range">> := _, <<"range">> := _}},
 		State=#state{etag=Etag}) ->
 	try cowboy_req:parse_header(<<"if-range">>, Req) of
 		%% Strong etag comparison is an exact match with the generate_etag result.
 		Etag={strong, _} ->
 			range(Req, State);
 		%% We cannot do a strong date comparison because we have
 		%% no way of knowing whether the representation changed
 		%% twice during the second covered by the presented
 		%% validator. (RFC7232 2.2.2)
 		_ ->
 			set_resp_body(Req, State)
 	catch _:_ ->
 		set_resp_body(Req, State)
 	end;
 if_range(Req, State) ->
 	range(Req, State).
 
 range(Req, State=#state{ranges_a=[]}) ->
 	set_resp_body(Req, State);
 range(Req, State) ->
 	try cowboy_req:parse_header(<<"range">>, Req) of
 		undefined ->
 			set_resp_body(Req, State);
 		%% @todo Maybe change parse_header to return <<"bytes">> in 3.0.
 		{bytes, BytesRange} ->
 			choose_range(Req, State, {<<"bytes">>, BytesRange});
 		Range ->
 			choose_range(Req, State, Range)
 	catch _:_ ->
 		%% We send a 416 response back when we can't parse the
 		%% range header at all. I'm not sure this is the right
 		%% way to go but at least this can help clients identify
 		%% what went wrong when their range requests never work.
 		range_not_satisfiable(Req, State, undefined)
 	end.
 
 choose_range(Req, State=#state{ranges_a=RangesAccepted}, Range={RangeUnit, _}) ->
 	case lists:keyfind(RangeUnit, 1, RangesAccepted) of
 		{_, Callback} ->
 			%% We pass the selected range onward in the Req.
 			range_satisfiable(Req#{range => Range}, State, Callback);
 		false ->
 			set_resp_body(Req, State)
 	end.
 
 range_satisfiable(Req, State, Callback) ->
 	case call(Req, State, range_satisfiable) of
 		no_call ->
 			set_ranged_body(Req, State, Callback);
 		{stop, Req2, State2} ->
 			terminate(Req2, State2);
 		{Switch, Req2, State2} when element(1, Switch) =:= switch_handler ->
 			switch_handler(Switch, Req2, State2);
 		{true, Req2, State2} ->
 			set_ranged_body(Req2, State2, Callback);
 		{false, Req2, State2} ->
 			range_not_satisfiable(Req2, State2, undefined);
 		{{false, Int}, Req2, State2} when is_integer(Int) ->
 			range_not_satisfiable(Req2, State2, [<<"*/">>, integer_to_binary(Int)]);
 		{{false, Iodata}, Req2, State2} when is_binary(Iodata); is_list(Iodata) ->
 			range_not_satisfiable(Req2, State2, Iodata)
 	end.
 
 %% When the callback selected is 'auto' and the range unit
 %% is bytes, we call the normal provide callback and split
 %% the content automatically.
 set_ranged_body(Req=#{range := {<<"bytes">>, _}}, State, auto) ->
 	set_ranged_body_auto(Req, State);
 set_ranged_body(Req, State, Callback) ->
 	set_ranged_body_callback(Req, State, Callback).
 
 set_ranged_body_auto(Req, State=#state{handler=Handler, content_type_a={_, Callback}}) ->
 	try case call(Req, State, Callback) of
 		{stop, Req2, State2} ->
 			terminate(Req2, State2);
 		{Switch, Req2, State2} when element(1, Switch) =:= switch_handler ->
 			switch_handler(Switch, Req2, State2);
 		{Body, Req2, State2} ->
 			maybe_set_ranged_body_auto(Req2, State2, Body)
 	end catch Class:{case_clause, no_call}:Stacktrace ->
 		error_terminate(Req, State, Class, {error, {missing_callback, {Handler, Callback, 2}},
 			'A callback specified in content_types_provided/2 is not exported.'},
 			Stacktrace)
 	end.
 
 maybe_set_ranged_body_auto(Req=#{range := {_, Ranges}}, State, Body) ->
 	Size = case Body of
 		{sendfile, _, Bytes, _} -> Bytes;
 		_ -> iolist_size(Body)
 	end,
 	Checks = [case Range of
 		{From, infinity} -> From < Size;
 		{From, To} -> (From < Size) andalso (From =< To) andalso (To =< Size);
 		Neg -> (Neg =/= 0) andalso (-Neg < Size)
 	end || Range <- Ranges],
 	case lists:usort(Checks) of
 		[true] -> set_ranged_body_auto(Req, State, Body);
 		_ -> range_not_satisfiable(Req, State, [<<"*/">>, integer_to_binary(Size)])
 	end.
 
 %% We might also want to have some checks about range order,
 %% number of ranges, and perhaps also join ranges that are
 %% too close into one contiguous range. Some of these can
 %% be done before calling the ProvideCallback.
 
 set_ranged_body_auto(Req=#{range := {_, Ranges}}, State, Body) ->
 	Parts = [ranged_partition(Range, Body) || Range <- Ranges],
 	case Parts of
 		[OnePart] -> set_one_ranged_body(Req, State, OnePart);
 		_ when is_tuple(Body) -> send_multipart_ranged_body(Req, State, Parts);
 		_ -> set_multipart_ranged_body(Req, State, Parts)
 	end.
 
 ranged_partition(Range, {sendfile, Offset0, Bytes0, Path}) ->
 	{From, To, Offset, Bytes} = case Range of
 		{From0, infinity} -> {From0, Bytes0 - 1, Offset0 + From0, Bytes0 - From0};
 		{From0, To0} -> {From0, To0, Offset0 + From0, 1 + To0 - From0};
 		Neg -> {Bytes0 + Neg, Bytes0 - 1, Offset0 + Bytes0 + Neg, -Neg}
 	end,
 	{{From, To, Bytes0}, {sendfile, Offset, Bytes, Path}};
 ranged_partition(Range, Data0) ->
 	Total = iolist_size(Data0),
 	{From, To, Data} = case Range of
 		{From0, infinity} ->
 			{_, Data1} = cow_iolists:split(From0, Data0),
 			{From0, Total - 1, Data1};
 		{From0, To0} ->
 			{_, Data1} = cow_iolists:split(From0, Data0),
 			{Data2, _} = cow_iolists:split(To0 - From0 + 1, Data1),
 			{From0, To0, Data2};
 		Neg ->
 			{_, Data1} = cow_iolists:split(Total + Neg, Data0),
 			{Total + Neg, Total - 1, Data1}
 	end,
 	{{From, To, Total}, Data}.
 
 -ifdef(TEST).
 ranged_partition_test_() ->
 	Tests = [
 		%% Sendfile with open-ended range.
 		{{0, infinity}, {sendfile, 0, 12, "t"}, {{0, 11, 12}, {sendfile, 0, 12, "t"}}},
 		{{6, infinity}, {sendfile, 0, 12, "t"}, {{6, 11, 12}, {sendfile, 6, 6, "t"}}},
 		{{11, infinity}, {sendfile, 0, 12, "t"}, {{11, 11, 12}, {sendfile, 11, 1, "t"}}},
 		%% Sendfile with open-ended range. Sendfile tuple has an offset originally.
 		{{0, infinity}, {sendfile, 3, 12, "t"}, {{0, 11, 12}, {sendfile, 3, 12, "t"}}},
 		{{6, infinity}, {sendfile, 3, 12, "t"}, {{6, 11, 12}, {sendfile, 9, 6, "t"}}},
 		{{11, infinity}, {sendfile, 3, 12, "t"}, {{11, 11, 12}, {sendfile, 14, 1, "t"}}},
 		%% Sendfile with a specific range.
 		{{0, 11}, {sendfile, 0, 12, "t"}, {{0, 11, 12}, {sendfile, 0, 12, "t"}}},
 		{{6, 11}, {sendfile, 0, 12, "t"}, {{6, 11, 12}, {sendfile, 6, 6, "t"}}},
 		{{11, 11}, {sendfile, 0, 12, "t"}, {{11, 11, 12}, {sendfile, 11, 1, "t"}}},
 		{{1, 10}, {sendfile, 0, 12, "t"}, {{1, 10, 12}, {sendfile, 1, 10, "t"}}},
 		%% Sendfile with a specific range. Sendfile tuple has an offset originally.
 		{{0, 11}, {sendfile, 3, 12, "t"}, {{0, 11, 12}, {sendfile, 3, 12, "t"}}},
 		{{6, 11}, {sendfile, 3, 12, "t"}, {{6, 11, 12}, {sendfile, 9, 6, "t"}}},
 		{{11, 11}, {sendfile, 3, 12, "t"}, {{11, 11, 12}, {sendfile, 14, 1, "t"}}},
 		{{1, 10}, {sendfile, 3, 12, "t"}, {{1, 10, 12}, {sendfile, 4, 10, "t"}}},
 		%% Sendfile with negative range.
 		{-12, {sendfile, 0, 12, "t"}, {{0, 11, 12}, {sendfile, 0, 12, "t"}}},
 		{-6, {sendfile, 0, 12, "t"}, {{6, 11, 12}, {sendfile, 6, 6, "t"}}},
 		{-1, {sendfile, 0, 12, "t"}, {{11, 11, 12}, {sendfile, 11, 1, "t"}}},
 		%% Sendfile with negative range. Sendfile tuple has an offset originally.
 		{-12, {sendfile, 3, 12, "t"}, {{0, 11, 12}, {sendfile, 3, 12, "t"}}},
 		{-6, {sendfile, 3, 12, "t"}, {{6, 11, 12}, {sendfile, 9, 6, "t"}}},
 		{-1, {sendfile, 3, 12, "t"}, {{11, 11, 12}, {sendfile, 14, 1, "t"}}},
 		%% Iodata with open-ended range.
 		{{0, infinity}, <<"Hello world!">>, {{0, 11, 12}, <<"Hello world!">>}},
 		{{6, infinity}, <<"Hello world!">>, {{6, 11, 12}, <<"world!">>}},
 		{{11, infinity}, <<"Hello world!">>, {{11, 11, 12}, <<"!">>}},
 		%% Iodata with a specific range. The resulting data is
 		%% wrapped in a list because of how cow_iolists:split/2 works.
 		{{0, 11}, <<"Hello world!">>, {{0, 11, 12}, [<<"Hello world!">>]}},
 		{{6, 11}, <<"Hello world!">>, {{6, 11, 12}, [<<"world!">>]}},
 		{{11, 11}, <<"Hello world!">>, {{11, 11, 12}, [<<"!">>]}},
 		{{1, 10}, <<"Hello world!">>, {{1, 10, 12}, [<<"ello world">>]}},
 		%% Iodata with negative range.
 		{-12, <<"Hello world!">>, {{0, 11, 12}, <<"Hello world!">>}},
 		{-6, <<"Hello world!">>, {{6, 11, 12}, <<"world!">>}},
 		{-1, <<"Hello world!">>, {{11, 11, 12}, <<"!">>}}
 	],
 	[{iolist_to_binary(io_lib:format("range ~p data ~p", [VR, VD])),
 		fun() -> R = ranged_partition(VR, VD) end} || {VR, VD, R} <- Tests].
 -endif.
 
 set_ranged_body_callback(Req, State=#state{handler=Handler}, Callback) ->
 	try case call(Req, State, Callback) of
 		{stop, Req2, State2} ->
 			terminate(Req2, State2);
 		{Switch, Req2, State2} when element(1, Switch) =:= switch_handler ->
 			switch_handler(Switch, Req2, State2);
 		%% When we receive a single range, we send it directly.
 		{[OneRange], Req2, State2} ->
 			set_one_ranged_body(Req2, State2, OneRange);
 		%% When we receive multiple ranges we have to send them as multipart/byteranges.
 		%% This also applies to non-bytes units. (RFC7233 A) If users don't want to use
 		%% this for non-bytes units they can always return a single range with a binary
 		%% content-range information.
 		{Ranges, Req2, State2} when length(Ranges) > 1 ->
 			%% We have to check whether there are sendfile tuples in the
 			%% ranges to be sent. If there are we must use stream_reply.
 			HasSendfile = [] =/= [true || {_, {sendfile, _, _, _}} <- Ranges],
 			case HasSendfile of
 				true -> send_multipart_ranged_body(Req2, State2, Ranges);
 				false -> set_multipart_ranged_body(Req2, State2, Ranges)
 			end
 	end catch Class:{case_clause, no_call}:Stacktrace ->
 		error_terminate(Req, State, Class, {error, {missing_callback, {Handler, Callback, 2}},
 			'A callback specified in ranges_provided/2 is not exported.'},
 			Stacktrace)
 	end.
 
 set_one_ranged_body(Req0, State, OneRange) ->
 	{ContentRange, Body} = prepare_range(Req0, OneRange),
 	Req1 = cowboy_req:set_resp_header(<<"content-range">>, ContentRange, Req0),
 	Req = cowboy_req:set_resp_body(Body, Req1),
 	respond(Req, State, 206).
 
 set_multipart_ranged_body(Req, State, [FirstRange|MoreRanges]) ->
 	Boundary = cow_multipart:boundary(),
 	ContentType = cowboy_req:resp_header(<<"content-type">>, Req),
 	{FirstContentRange, FirstPartBody} = prepare_range(Req, FirstRange),
 	FirstPartHead = cow_multipart:first_part(Boundary, [
 		{<<"content-type">>, ContentType},
 		{<<"content-range">>, FirstContentRange}
 	]),
 	MoreParts = [begin
 		{NextContentRange, NextPartBody} = prepare_range(Req, NextRange),
 		NextPartHead = cow_multipart:part(Boundary, [
 			{<<"content-type">>, ContentType},
 			{<<"content-range">>, NextContentRange}
 		]),
 		[NextPartHead, NextPartBody]
 	end || NextRange <- MoreRanges],
 	Body = [FirstPartHead, FirstPartBody, MoreParts, cow_multipart:close(Boundary)],
 	Req2 = cowboy_req:set_resp_header(<<"content-type">>,
 		[<<"multipart/byteranges; boundary=">>, Boundary], Req),
 	Req3 = cowboy_req:set_resp_body(Body, Req2),
 	respond(Req3, State, 206).
 
 %% Similar to set_multipart_ranged_body except we have to stream
 %% the data because the parts contain sendfile tuples.
 send_multipart_ranged_body(Req, State, [FirstRange|MoreRanges]) ->
 	Boundary = cow_multipart:boundary(),
 	ContentType = cowboy_req:resp_header(<<"content-type">>, Req),
 	Req2 = cowboy_req:set_resp_header(<<"content-type">>,
 		[<<"multipart/byteranges; boundary=">>, Boundary], Req),
 	Req3 = cowboy_req:stream_reply(206, Req2),
 	{FirstContentRange, FirstPartBody} = prepare_range(Req, FirstRange),
 	FirstPartHead = cow_multipart:first_part(Boundary, [
 		{<<"content-type">>, ContentType},
 		{<<"content-range">>, FirstContentRange}
 	]),
 	cowboy_req:stream_body(FirstPartHead, nofin, Req3),
 	cowboy_req:stream_body(FirstPartBody, nofin, Req3),
 	_ = [begin
 		{NextContentRange, NextPartBody} = prepare_range(Req, NextRange),
 		NextPartHead = cow_multipart:part(Boundary, [
 			{<<"content-type">>, ContentType},
 			{<<"content-range">>, NextContentRange}
 		]),
 		cowboy_req:stream_body(NextPartHead, nofin, Req3),
 		cowboy_req:stream_body(NextPartBody, nofin, Req3),
 		[NextPartHead, NextPartBody]
 	end || NextRange <- MoreRanges],
 	cowboy_req:stream_body(cow_multipart:close(Boundary), fin, Req3),
 	terminate(Req3, State).
 
 prepare_range(#{range := {RangeUnit, _}}, {{From, To, Total0}, Body}) ->
 	Total = case Total0 of
 		'*' -> <<"*">>;
 		_ -> integer_to_binary(Total0)
 	end,
 	ContentRange = [RangeUnit, $\s, integer_to_binary(From),
 		$-, integer_to_binary(To), $/, Total],
 	{ContentRange, Body};
 prepare_range(#{range := {RangeUnit, _}}, {RangeData, Body}) ->
 	{[RangeUnit, $\s, RangeData], Body}.
 
 %% We send the content-range header when we can on error.
 range_not_satisfiable(Req, State, undefined) ->
 	respond(Req, State, 416);
 range_not_satisfiable(Req0=#{range := {RangeUnit, _}}, State, RangeData) ->
 	Req = cowboy_req:set_resp_header(<<"content-range">>,
 		[RangeUnit, $\s, RangeData], Req0),
 	respond(Req, State, 416).
 
 %% Set the response headers and call the callback found using
 %% content_types_provided/2 to obtain the request body and add
 %% it to the response.
 set_resp_body(Req, State=#state{handler=Handler, content_type_a={_, Callback}}) ->
 	try case call(Req, State, Callback) of
 		{stop, Req2, State2} ->
 			terminate(Req2, State2);
 		{Switch, Req2, State2} when element(1, Switch) =:= switch_handler ->
 			switch_handler(Switch, Req2, State2);
 		{Body, Req2, State2} ->
 			Req3 = cowboy_req:set_resp_body(Body, Req2),
 			multiple_choices(Req3, State2)
 	end catch Class:{case_clause, no_call}:Stacktrace ->
 		error_terminate(Req, State, Class, {error, {missing_callback, {Handler, Callback, 2}},
 			'A callback specified in content_types_provided/2 is not exported.'},
 			Stacktrace)
 	end.
 
 multiple_choices(Req, State) ->
 	expect(Req, State, multiple_choices, false, 200, 300).
 
 %% Response utility functions.
 
 set_resp_etag(Req, State) ->
 	{Etag, Req2, State2} = generate_etag(Req, State),
 	case Etag of
 		undefined ->
 			{Req2, State2};
 		Etag ->
 			Req3 = cowboy_req:set_resp_header(
 				<<"etag">>, encode_etag(Etag), Req2),
 			{Req3, State2}
 	end.
 
 -spec encode_etag({strong | weak, binary()}) -> iolist().
 encode_etag({strong, Etag}) -> [$",Etag,$"];
 encode_etag({weak, Etag}) -> ["W/\"",Etag,$"].
 
 set_resp_expires(Req, State) ->
 	{Expires, Req2, State2} = expires(Req, State),
 	case Expires of
 		Expires when is_atom(Expires) ->
 			{Req2, State2};
 		Expires when is_binary(Expires) ->
 			Req3 = cowboy_req:set_resp_header(
 				<<"expires">>, Expires, Req2),
 			{Req3, State2};
 		Expires ->
 			ExpiresBin = cowboy_clock:rfc1123(Expires),
 			Req3 = cowboy_req:set_resp_header(
 				<<"expires">>, ExpiresBin, Req2),
 			{Req3, State2}
 	end.
 
 %% Info retrieval. No logic.
 
 generate_etag(Req, State=#state{etag=no_call}) ->
 	{undefined, Req, State};
 generate_etag(Req, State=#state{etag=undefined}) ->
 	case unsafe_call(Req, State, generate_etag) of
 		no_call ->
 			{undefined, Req, State#state{etag=no_call}};
 		{Etag, Req2, State2} when is_binary(Etag) ->
 			Etag2 = cow_http_hd:parse_etag(Etag),
 			{Etag2, Req2, State2#state{etag=Etag2}};
 		{Etag, Req2, State2} ->
 			{Etag, Req2, State2#state{etag=Etag}}
 	end;
 generate_etag(Req, State=#state{etag=Etag}) ->
 	{Etag, Req, State}.
 
 last_modified(Req, State=#state{last_modified=no_call}) ->
 	{undefined, Req, State};
 last_modified(Req, State=#state{last_modified=undefined}) ->
 	case unsafe_call(Req, State, last_modified) of
 		no_call ->
 			{undefined, Req, State#state{last_modified=no_call}};
 		{LastModified, Req2, State2} ->
 			{LastModified, Req2, State2#state{last_modified=LastModified}}
 	end;
 last_modified(Req, State=#state{last_modified=LastModified}) ->
 	{LastModified, Req, State}.
 
 expires(Req, State=#state{expires=no_call}) ->
 	{undefined, Req, State};
 expires(Req, State=#state{expires=undefined}) ->
 	case unsafe_call(Req, State, expires) of
 		no_call ->
 			{undefined, Req, State#state{expires=no_call}};
 		{Expires, Req2, State2} ->
 			{Expires, Req2, State2#state{expires=Expires}}
 	end;
 expires(Req, State=#state{expires=Expires}) ->
 	{Expires, Req, State}.
 
 %% REST primitives.
 
 expect(Req, State, Callback, Expected, OnTrue, OnFalse) ->
 	case call(Req, State, Callback) of
 		no_call ->
 			next(Req, State, OnTrue);
 		{stop, Req2, State2} ->
 			terminate(Req2, State2);
 		{Switch, Req2, State2} when element(1, Switch) =:= switch_handler ->
 			switch_handler(Switch, Req2, State2);
 		{Expected, Req2, State2} ->
 			next(Req2, State2, OnTrue);
 		{_Unexpected, Req2, State2} ->
 			next(Req2, State2, OnFalse)
 	end.
 
 call(Req0, State=#state{handler=Handler,
 		handler_state=HandlerState0}, Callback) ->
 	case erlang:function_exported(Handler, Callback, 2) of
 		true ->
 			try Handler:Callback(Req0, HandlerState0) of
 				no_call ->
 					no_call;
 				{Result, Req, HandlerState} ->
 					{Result, Req, State#state{handler_state=HandlerState}}
 			catch Class:Reason:Stacktrace ->
 				error_terminate(Req0, State, Class, Reason, Stacktrace)
 			end;
 		false ->
 			no_call
 	end.
 
 unsafe_call(Req0, State=#state{handler=Handler,
 		handler_state=HandlerState0}, Callback) ->
 	case erlang:function_exported(Handler, Callback, 2) of
 		false ->
 			no_call;
 		true ->
 			case Handler:Callback(Req0, HandlerState0) of
 				no_call ->
 					no_call;
 				{Result, Req, HandlerState} ->
 					{Result, Req, State#state{handler_state=HandlerState}}
 			end
 	end.
 
 next(Req, State, Next) when is_function(Next) ->
 	Next(Req, State);
 next(Req, State, StatusCode) when is_integer(StatusCode) ->
 	respond(Req, State, StatusCode).
 
 respond(Req0, State, StatusCode) ->
 	%% We remove the content-type header when there is no body,
 	%% except when the status code is 200 because it might have
 	%% been intended (for example sending an empty file).
 	Req = case cowboy_req:has_resp_body(Req0) of
 		true when StatusCode =:= 200 -> Req0;
 		true -> Req0;
 		false -> cowboy_req:delete_resp_header(<<"content-type">>, Req0)
 	end,
 	terminate(cowboy_req:reply(StatusCode, Req), State).
 
 switch_handler({switch_handler, Mod}, Req, #state{handler_state=HandlerState}) ->
 	{Mod, Req, HandlerState};
 switch_handler({switch_handler, Mod, Opts}, Req, #state{handler_state=HandlerState}) ->
 	{Mod, Req, HandlerState, Opts}.
 
 -spec error_terminate(cowboy_req:req(), #state{}, atom(), any(), any()) -> no_return().
 error_terminate(Req, #state{handler=Handler, handler_state=HandlerState}, Class, Reason, Stacktrace) ->
 	cowboy_handler:terminate({crash, Class, Reason}, Req, HandlerState, Handler),
 	erlang:raise(Class, Reason, Stacktrace).
 
 terminate(Req, #state{handler=Handler, handler_state=HandlerState}) ->
 	Result = cowboy_handler:terminate(normal, Req, HandlerState, Handler),
 	{ok, Req, Result}.