Document the cookie store option and related modules

Also contains a few small changes and Dialyzer fixes.

7 files changed, 356 insertions, 4 deletions

diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc
index c22f1ef..2067d96 100644
--- a/doc/src/manual/gun.asciidoc
+++ b/doc/src/manual/gun.asciidoc
@@ -251,6 +251,7 @@ Time between pings in milliseconds.
 ----
 opts() :: #{
     connect_timeout       => timeout(),
+    cookie_store          => gun_cookies:store(),
     domain_lookup_timeout => timeout(),
     http_opts             => http_opts(),
     http2_opts            => http2_opts(),
@@ -276,6 +277,15 @@ connect_timeout (infinity)::
 
 Connection timeout.
 
+cookie_store - see below::
+
+The cookie store that Gun will use for this connection.
+When configured, Gun will query the store for cookies
+and include them in the request headers; and add cookies
+found in response headers to the store.
++
+By default no cookie store will be used.
+
 domain_lookup_timeout (infinity)::
 
 Domain lookup timeout.
@@ -525,6 +535,9 @@ when receiving a ping.
 
 == Changelog
 
+* *2.0*: The option `cookie_store` was added. It can be used
+         to configure a cookie store that Gun will use
+         automatically.
 * *2.0*: The types `protocols()` and `socks_opts()` have been
          added. Support for the Socks protocol has been added
          in every places where protocol selection is available.
diff --git a/doc/src/manual/gun.info.asciidoc b/doc/src/manual/gun.info.asciidoc
index 8f98942..095492e 100644
--- a/doc/src/manual/gun.info.asciidoc
+++ b/doc/src/manual/gun.info.asciidoc
@@ -6,8 +6,6 @@ gun:info - Obtain information about the connection
 
 == Description
 
-// @todo Document the cookie_store key when documenting cookies.
-
 [source,erlang]
 ----
 info(ConnPid) -> Info
@@ -22,7 +20,8 @@ Info :: #{
     sock_port      => inet:port_number(),
     origin_host    => inet:hostname() | inet:ip_address(),
     origin_port    => inet:port_number(),
-    intermediaries => [Intermediary]
+    intermediaries => [Intermediary],
+    cookie_store   => gun_cookies:cookie_store()
 }
 Intermediary :: #{
     type      => connect | socks5,
@@ -48,7 +47,7 @@ the connection.
 
 == Changelog
 
-* *2.0*: The value `owner` was added.
+* *2.0*: The values `owner` and `cookie_store` were added.
 * *1.3*: The values `socket`, `transport`, `protocol`, `origin_host`,
          `origin_port` and `intermediaries` were added.
 * *1.0*: Function introduced.
diff --git a/doc/src/manual/gun_app.asciidoc b/doc/src/manual/gun_app.asciidoc
index c369095..6ebbfe8 100644
--- a/doc/src/manual/gun_app.asciidoc
+++ b/doc/src/manual/gun_app.asciidoc
@@ -16,6 +16,8 @@ to the server and reconnects automatically when necessary.
 == Modules
 
 * link:man:gun(3)[gun(3)] - Asynchronous HTTP client
+* link:man:gun_cookies(3)[gun_cookies(3)] - Cookie store engine
+* link:man:gun_cookies_list(3)[gun_cookies_list(3)] - Cookie store backend: in-memory, per connection
 
 == Dependencies
 
diff --git a/doc/src/manual/gun_cookies.asciidoc b/doc/src/manual/gun_cookies.asciidoc
new file mode 100644
index 0000000..06f1daf
--- /dev/null
+++ b/doc/src/manual/gun_cookies.asciidoc
@@ -0,0 +1,179 @@
+= gun_cookies(3)
+
+== Name
+
+gun_cookies - Cookie store engine
+
+== Description
+
+The `gun_cookies` module implements a cookie store engine.
+It will be used by Gun when a cookie store is configured.
+It also defines the interface and provides functions used
+to implement cookie store backends.
+
+== Callbacks
+
+Cookie store backends implement the following interface.
+Functions are organized by theme: initialization, querying,
+storing and garbage collecting:
+
+=== init
+
+[source,erlang]
+----
+init(Opts :: any()) -> gun_cookies:store()
+----
+
+Initialize the cookie store.
+
+=== query
+
+[source,erlang]
+----
+query(State, URI) -> {ok, [Cookie], State}
+
+URI    :: uri_string:uri_map()
+Cookie :: gun_cookies:cookie()
+State  :: any()
+----
+
+Query the store for the cookies for the given URI.
+
+=== set_cookie_secure_match
+
+[source,erlang]
+----
+set_cookie_secure_match(State, Match) -> match | nomatch
+
+State :: any()
+Match :: #{
+    name := binary(),
+%	secure_only := true,
+    domain := binary(),
+    path := binary()
+}
+----
+
+Perform a secure match against cookies already in the store.
+This is part of the heuristics that the cookie store engine
+applies to decide whether the cookie must be stored.
+
+The `secure_only` attribute is implied, it is not actually
+passed in the argument.
+
+=== set_cookie_get_exact_match
+
+[source,erlang]
+----
+set_cookie_get_exact_match(State, Match)
+    -> {ok, gun_cookies:cookie(), State} | error
+
+State :: any()
+Match :: #{
+	name := binary(),
+	domain := binary(),
+	host_only := boolean(),
+	path := binary()
+}
+----
+
+Perform an exact match against cookies already in the store.
+This is part of the heuristics that the cookie store engine
+applies to decide whether the cookie must be stored.
+
+When a cookie is found, it must be returned so that it gets
+updated. When nothing is found a new cookie will be stored.
+
+=== store
+
+[source,erlang]
+----
+store(State, gun_cookies:cookie())
+	-> {ok, State} | {error, any()}
+
+State :: any()
+----
+
+Unconditionally store the cookie into the cookie store.
+
+=== gc
+
+[source,erlang]
+----
+gc(State) -> {ok, State}
+
+State :: any()
+----
+
+Remove all cookies from the cookie store that are expired.
+
+Other cookies may be removed as well, at the discretion
+of the cookie store. For example excess cookies may be
+removed to reduce the memory footprint.
+
+=== session_gc
+
+[source,erlang]
+----
+session_gc(State) -> {ok, State}
+
+State :: any()
+----
+
+Remove all cookies from the cookie store that have the
+`persistent` flag set to `false`.
+
+== Exports
+
+* link:man:gun_cookies:domain_match(3)[gun_cookies:domain_match(3)] - Cookie domain match
+* link:man:gun_cookies:path_match(3)[gun_cookies:path_match(3)] - Cookie path match
+
+== Types
+
+=== cookie()
+
+[source,erlang]
+----
+cookie() :: #{
+    name             := binary(),
+    value            := binary(),
+    domain           := binary(),
+    path             := binary(),
+    creation_time    := calendar:datetime(),
+    last_access_time := calendar:datetime(),
+    expiry_time      := calendar:datetime() | infinity,
+    persistent       := boolean(),
+    host_only        := boolean(),
+    secure_only      := boolean(),
+    http_only        := boolean(),
+    same_site        := strict | lax | none
+}
+----
+
+A cookie.
+
+This contains the cookie name, value, attributes and flags.
+This is the representation that the cookie store engine
+and Gun expects. Cookies do not have to be kept in this
+format in the cookie store backend.
+
+=== store()
+
+[source,erlang]
+----
+store() :: {module(), StoreState :: any()}
+----
+
+The cookie store.
+
+This is a tuple containing the cookie store backend module
+and its current state.
+
+== Changelog
+
+* *2.0*: Module introduced.
+
+== See also
+
+link:man:gun(7)[gun(7)],
+link:man:gun_cookies_list(3)[gun_cookies_list(3)]
diff --git a/doc/src/manual/gun_cookies.domain_match.asciidoc b/doc/src/manual/gun_cookies.domain_match.asciidoc
new file mode 100644
index 0000000..34f52ec
--- /dev/null
+++ b/doc/src/manual/gun_cookies.domain_match.asciidoc
@@ -0,0 +1,52 @@
+= gun_cookies:domain_match(3)
+
+== Name
+
+gun_cookies:domain_match - Cookie domain match
+
+== Description
+
+[source,erlang]
+----
+domain_match(String, DomainString) -> boolean()
+
+String       :: binary()
+DomainString :: binary()
+----
+
+Cookie domain match.
+
+This function can be used when implementing the
+`set_cookie_secure_match` callback of a cookie store.
+
+== Arguments
+
+String::
+
+The string to match.
+
+DomainString::
+
+The domain string that will be matched against.
+
+== Return value
+
+Returns `true` when `String` domain-matches `DomainString`,
+and `false` otherwise.
+
+== Changelog
+
+* *2.0*: Function introduced.
+
+== Examples
+
+.Perform a domain match
+[source,erlang]
+----
+Match = gun_cookies:domain_match(Domain, CookieDomain).
+----
+
+== See also
+
+link:man:gun_cookies(3)[gun_cookies(3)],
+link:man:gun_cookies:path_match(3)[gun_cookies:path_match(3)]
diff --git a/doc/src/manual/gun_cookies.path_match.asciidoc b/doc/src/manual/gun_cookies.path_match.asciidoc
new file mode 100644
index 0000000..2e1771a
--- /dev/null
+++ b/doc/src/manual/gun_cookies.path_match.asciidoc
@@ -0,0 +1,52 @@
+= gun_cookies:path_match(3)
+
+== Name
+
+gun_cookies:path_match - Cookie path match
+
+== Description
+
+[source,erlang]
+----
+path_match(ReqPath, CookiePath) -> boolean()
+
+ReqPath    :: binary()
+CookiePath :: binary()
+----
+
+Cookie path match.
+
+This function can be used when implementing the
+`set_cookie_secure_match` callback of a cookie store.
+
+== Arguments
+
+ReqPath::
+
+The request path to match.
+
+CookiePath::
+
+The cookie path that will be matched against.
+
+== Return value
+
+Returns `true` when `ReqPath` path-matches `CookiePath`,
+and `false` otherwise.
+
+== Changelog
+
+* *2.0*: Function introduced.
+
+== Examples
+
+.Perform a path match
+[source,erlang]
+----
+Match = gun_cookies:path_match(ReqPath, CookiePath).
+----
+
+== See also
+
+link:man:gun_cookies(3)[gun_cookies(3)],
+link:man:gun_cookies:domain_match(3)[gun_cookies:domain_match(3)]
diff --git a/doc/src/manual/gun_cookies_list.asciidoc b/doc/src/manual/gun_cookies_list.asciidoc
new file mode 100644
index 0000000..2daef8e
--- /dev/null
+++ b/doc/src/manual/gun_cookies_list.asciidoc
@@ -0,0 +1,55 @@
+= gun_cookies_list(3)
+
+== Name
+
+gun_cookies_list - Cookie store backend: in-memory, per connection
+
+== Description
+
+The `gun_cookies_list` module implements a cookie store
+backend that keeps all the cookie data in-memory and tied
+to a specific connection.
+
+It is possible to implement a custom backend on top of
+`gun_cookies_list` in order to add persistence or sharing
+properties.
+
+== Exports
+
+This module implements the callbacks defined in
+link:man:gun_cookies(3)[gun_cookies(3)].
+
+== Types
+
+=== opts()
+
+[source,erlang]
+----
+opts() :: #{
+}
+----
+
+Cookie store backend options.
+
+There are currently no options available for this backend.
+
+// The default value is given next to the option name:
+
+== Changelog
+
+* *2.0*: Module introduced.
+
+== Examples
+
+.Open a connection with a cookie store configured
+[source,erlang]
+----
+{ok, ConnPid} = gun:open(Host, Port, #{
+    cookie_store => gun_cookies_list:init(#{})
+})
+----
+
+== See also
+
+link:man:gun(7)[gun(7)],
+link:man:gun_cookies(3)[gun_cookies(3)]