diff options
author | Loïc Hoguin <[email protected]> | 2020-03-15 18:41:48 +0100 |
---|---|---|
committer | Loïc Hoguin <[email protected]> | 2020-03-15 18:41:48 +0100 |
commit | e37af7ac0caffc661def1593c55b212cc2f05d3e (patch) | |
tree | 0e55296085281e8360261394259c9988b4bd83ac /doc/src/manual/gun_cookies.asciidoc | |
parent | 87d0bfff926892d2dc0a55a3dc45d8c5f8a682f3 (diff) | |
download | gun-e37af7ac0caffc661def1593c55b212cc2f05d3e.tar.gz gun-e37af7ac0caffc661def1593c55b212cc2f05d3e.tar.bz2 gun-e37af7ac0caffc661def1593c55b212cc2f05d3e.zip |
Document the cookie store option and related modules
Also contains a few small changes and Dialyzer fixes.
Diffstat (limited to 'doc/src/manual/gun_cookies.asciidoc')
-rw-r--r-- | doc/src/manual/gun_cookies.asciidoc | 179 |
1 files changed, 179 insertions, 0 deletions
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)] |