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

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

Types

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.

See also

gun(7), gun_cookies_list(3)

Gun 2.1 Function Reference

Navigation

Version select

Like my work? Donate!

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.