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

init(Opts :: any()) -> gun_cookies:store()

Initialize the cookie store.

query

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

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

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

store(State, gun_cookies:cookie())
        -> {ok, State} | {error, any()}

State :: any()

Unconditionally store the cookie into the cookie store.

gc

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

session_gc(State) -> {ok, State}

State :: any()

Remove all cookies from the cookie store that have the persistent flag set to false.

Exports

gun_cookies:domain_match(3) - Cookie domain match
gun_cookies:path_match(3) - Cookie path match

Types

cookie()

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()

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.