diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/manual/gun.asciidoc | 13 | ||||
| -rw-r--r-- | doc/src/manual/gun.info.asciidoc | 7 | ||||
| -rw-r--r-- | doc/src/manual/gun_app.asciidoc | 2 | ||||
| -rw-r--r-- | doc/src/manual/gun_cookies.asciidoc | 179 | ||||
| -rw-r--r-- | doc/src/manual/gun_cookies.domain_match.asciidoc | 52 | ||||
| -rw-r--r-- | doc/src/manual/gun_cookies.path_match.asciidoc | 52 | ||||
| -rw-r--r-- | doc/src/manual/gun_cookies_list.asciidoc | 55 |
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)] |