From 28aee1f2720da122f83758b141c503f7bff18ffb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Thu, 3 Oct 2019 16:20:29 +0200
Subject: Document media type wildcard in content_types_accepted

---
 doc/src/manual/cowboy_rest.asciidoc        |  6 +++++-
 src/cowboy_rest.erl                        |  2 +-
 test/handlers/content_types_accepted_h.erl |  2 ++
 test/rest_handler_SUITE.erl                | 18 ++++++++++++++++++
 4 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/doc/src/manual/cowboy_rest.asciidoc b/doc/src/manual/cowboy_rest.asciidoc
index d7901fd..b783a25 100644
--- a/doc/src/manual/cowboy_rest.asciidoc
+++ b/doc/src/manual/cowboy_rest.asciidoc
@@ -184,7 +184,7 @@ content-type header of the response if the media type is text.
 ----
 content_types_accepted(Req, State) -> {Result, Req, State}
 
-Result     :: [{binary() | ParsedMime, AcceptCallback :: atom()}]
+Result     :: [{'*' | binary() | ParsedMime, AcceptCallback :: atom()}]
 ParsedMime :: {Type :: binary(), SubType :: binary(), '*' | Params}
 Params     :: [{Key :: binary(), Value :: binary()}]
 
@@ -200,6 +200,8 @@ A media type is made of different parts. The media type
 `text/html;charset=utf-8` is of type `text`, subtype `html`
 and has a single parameter `charset` with value `utf-8`.
 
+The special value `'*'` can be used to accept any media type.
+
 // @todo Cowboy needs to ignore the boundary parameter for
 // multipart, as we never want to match against it. Or allow
 // ignoring specific parameters at the very least.
@@ -724,6 +726,8 @@ listed here, like the authorization header.
 
 == Changelog
 
+* *2.7*: The media type wildcard in `content_types_accepted`
+         is now documented.
 * *2.6*: The callback `rate_limited` was added.
 * *2.1*: The `switch_handler` return value was added.
 * *1.0*: Behavior introduced.
diff --git a/src/cowboy_rest.erl b/src/cowboy_rest.erl
index 7be3e26..9a73374 100644
--- a/src/cowboy_rest.erl
+++ b/src/cowboy_rest.erl
@@ -61,7 +61,7 @@
 -optional_callbacks([charsets_provided/2]).
 
 -callback content_types_accepted(Req, State)
-	-> {[{binary() | {binary(), binary(), '*' | [{binary(), binary()}]}, atom()}], Req, State}
+	-> {[{'*' | binary() | {binary(), binary(), '*' | [{binary(), binary()}]}, atom()}], Req, State}
 	| {stop, Req, State}
 	| {switch_handler(), Req, State}
 	when Req::cowboy_req:req(), State::any().
diff --git a/test/handlers/content_types_accepted_h.erl b/test/handlers/content_types_accepted_h.erl
index d34135e..df72f06 100644
--- a/test/handlers/content_types_accepted_h.erl
+++ b/test/handlers/content_types_accepted_h.erl
@@ -21,6 +21,8 @@ content_types_accepted(Req=#{qs := <<"multipart">>}, State) ->
 	], Req, State};
 content_types_accepted(Req=#{qs := <<"param">>}, State) ->
 	{[{{<<"text">>, <<"plain">>, [{<<"charset">>, <<"utf-8">>}]}, put_text_plain}], Req, State};
+content_types_accepted(Req=#{qs := <<"wildcard">>}, State) ->
+	{[{'*', put_text_plain}], Req, State};
 content_types_accepted(Req=#{qs := <<"wildcard-param">>}, State) ->
 	{[{{<<"text">>, <<"plain">>, '*'}, put_text_plain}], Req, State}.
 
diff --git a/test/rest_handler_SUITE.erl b/test/rest_handler_SUITE.erl
index cb734d9..43695c3 100644
--- a/test/rest_handler_SUITE.erl
+++ b/test/rest_handler_SUITE.erl
@@ -359,6 +359,24 @@ content_types_accepted_param(Config) ->
 	{response, fin, 204, _} = gun:await(ConnPid, Ref),
 	ok.
 
+content_types_accepted_wildcard(Config) ->
+	doc("When a wildcard is returned from the content_types_accepted "
+		"callback, any content-type must be accepted."),
+	ConnPid = gun_open(Config),
+	Ref1 = gun:put(ConnPid, "/content_types_accepted?wildcard", [
+		{<<"accept-encoding">>, <<"gzip">>},
+		{<<"content-type">>, <<"text/plain">>}
+	]),
+	gun:data(ConnPid, Ref1, fin, "Hello world!"),
+	{response, fin, 204, _} = gun:await(ConnPid, Ref1),
+	Ref2 = gun:put(ConnPid, "/content_types_accepted?wildcard", [
+		{<<"accept-encoding">>, <<"gzip">>},
+		{<<"content-type">>, <<"application/vnd.plain;charset=UTF-8">>}
+	]),
+	gun:data(ConnPid, Ref2, fin, "Hello world!"),
+	{response, fin, 204, _} = gun:await(ConnPid, Ref2),
+	ok.
+
 content_types_accepted_wildcard_param_no_content_type_param(Config) ->
 	doc("When a wildcard is returned for parameters from the "
 		"content_types_accepted callback, a content-type header "
-- 
cgit v1.2.3