Document the cookie store option and related modules

Also contains a few small changes and Dialyzer fixes.

3 files changed, 17 insertions, 14 deletions

diff --git a/src/gun.erl b/src/gun.erl
index 7e468f3..b8030cf 100644
--- a/src/gun.erl
+++ b/src/gun.erl
@@ -1585,7 +1585,7 @@ owner_down(Reason, State) -> {stop, {shutdown, {owner_down, Reason}}, State}.
 
 terminate(Reason, StateName, #state{event_handler=EvHandler,
 		event_handler_state=EvHandlerState, cookie_store=Store}) ->
-	case Store of
+	_ = case Store of
 		undefined -> ok;
 		%% Optimization: gun_cookies_list isn't a persistent cookie store.
 		{gun_cookies_list, _} -> ok;
diff --git a/src/gun_cookies.erl b/src/gun_cookies.erl
index d4c5423..b8fa4da 100644
--- a/src/gun_cookies.erl
+++ b/src/gun_cookies.erl
@@ -39,7 +39,7 @@
 	last_access_time := calendar:datetime(),
 	expiry_time := calendar:datetime() | infinity,
 	persistent := boolean(),
-	host_only => boolean(),
+	host_only := boolean(),
 	secure_only := boolean(),
 	http_only := boolean(),
 	same_site := strict | lax | none
@@ -49,7 +49,7 @@
 -callback init(any()) -> store().
 
 -callback query(State, uri_string:uri_map())
-	-> {ok, [{binary(), binary()}], State}
+	-> {ok, [gun_cookies:cookie()], State}
 	when State::store_state().
 
 -callback set_cookie_secure_match(store_state(), #{
@@ -59,12 +59,13 @@
 	path := binary()
 }) -> match | nomatch.
 
--callback set_cookie_exact_match(store_state(), #{
+-callback set_cookie_get_exact_match(State, #{
 	name := binary(),
 	domain := binary(),
 	host_only := boolean(),
 	path := binary()
-}) -> {match, cookie()} | nomatch.
+}) -> {ok, cookie(), State} | error
+	when State::store_state().
 
 -callback store(State, cookie())
 	-> {ok, State} | {error, any()}
@@ -137,7 +138,7 @@ path_match_test_() ->
 
 %% @todo The given URI must be normalized.
 -spec query(Store, uri_string:uri_map())
-	-> {ok, [{binary(), binary()}], Store}
+	-> {ok, [cookie()], Store}
 	when Store::store().
 query({Mod, State0}, URI) ->
 	{ok, Cookies0, State} = Mod:query(State0, URI),
@@ -288,7 +289,7 @@ set_cookie3(Store, Attrs, Cookie=#{name := Name,
 
 set_cookie_store(Store0, Cookie) ->
 	Match = maps:with([name, domain, host_only, path], Cookie),
-	case set_cookie_take_exact_match(Store0, Match) of
+	case set_cookie_get_exact_match(Store0, Match) of
 		{ok, #{creation_time := CreationTime}, Store} ->
 			%% This is where we would reject a new non-HTTP cookie
 			%% if the OldCookie has http_only set to true.
@@ -297,8 +298,8 @@ set_cookie_store(Store0, Cookie) ->
 			store(Store0, Cookie)
 	end.
 
-set_cookie_take_exact_match({Mod, State0}, Match) ->
-	case Mod:set_cookie_take_exact_match(State0, Match) of
+set_cookie_get_exact_match({Mod, State0}, Match) ->
+	case Mod:set_cookie_get_exact_match(State0, Match) of
 		{ok, Cookie, State} ->
 			{ok, Cookie, {Mod, State}};
 		Error ->
@@ -624,5 +625,5 @@ wpt_secure_http_test() ->
 	{error, secure_scheme_only} = set_cookie(gun_cookies_list:init(), URIMap, N, V, A),
 	ok.
 
-%% @todo WPT: secure/set-from-ws* - Anything special required?
+%% WPT: secure/set-from-ws* (Anything special required?)
 -endif.
diff --git a/src/gun_cookies_list.erl b/src/gun_cookies_list.erl
index e8cf17a..77cc236 100644
--- a/src/gun_cookies_list.erl
+++ b/src/gun_cookies_list.erl
@@ -15,12 +15,13 @@
 %% A reference cookie store implemented as a list of cookies.
 %% This cookie store cannot be shared between connections.
 -module(gun_cookies_list).
+-behavior(gun_cookies).
 
 -export([init/0]).
 -export([init/1]).
 -export([query/2]).
 -export([set_cookie_secure_match/2]).
--export([set_cookie_take_exact_match/2]).
+-export([set_cookie_get_exact_match/2]).
 -export([store/2]).
 -export([gc/1]).
 -export([session_gc/1]).
@@ -33,6 +34,7 @@
 
 -type opts() :: #{
 }.
+-export_type([opts/0]).
 
 -spec init() -> {?MODULE, state()}.
 init() ->
@@ -43,7 +45,7 @@ init(_Opts) ->
 	{?MODULE, #{cookies => []}}.
 
 -spec query(State, uri_string:uri_map())
-	-> {ok, [{binary(), binary()}], State}
+	-> {ok, [gun_cookies:cookie()], State}
 	when State::state().
 query(State=#{cookies := Cookies}, URI) ->
 	CurrentTime = erlang:universaltime(),
@@ -100,13 +102,13 @@ set_cookie_secure_match(#{cookies := Cookies},
 		_ -> match
 	end.
 
--spec set_cookie_take_exact_match(State, #{
+-spec set_cookie_get_exact_match(State, #{
 	name := binary(),
 	domain := binary(),
 	host_only := boolean(),
 	path := binary()
 }) -> {ok, gun_cookies:cookie(), State} | error when State::state().
-set_cookie_take_exact_match(State=#{cookies := Cookies0}, Match) ->
+set_cookie_get_exact_match(State=#{cookies := Cookies0}, Match) ->
 	Result = [Cookie || Cookie <- Cookies0,
 		Match =:= maps:with([name, domain, host_only, path], Cookie)],
 	Cookies = [Cookie || Cookie <- Cookies0,