mirror of
https://github.com/ninenines/cowboy.git
synced 2025-07-15 04:30:25 +00:00
142 lines
4.4 KiB
Text
142 lines
4.4 KiB
Text
[[cookies]]
|
|
== Using cookies
|
|
|
|
Cookies are a mechanism allowing applications to maintain
|
|
state on top of the stateless HTTP protocol.
|
|
|
|
Cookies are a name/value store where the names and values are
|
|
stored in plain text. They expire either after a delay
|
|
or when the browser closes. They can be configured on a
|
|
specific domain name or path, and restricted to secure
|
|
resources (sent or downloaded over HTTPS), or restricted
|
|
to the server (disallowing access from client-side scripts).
|
|
|
|
Cookie names are de facto case sensitive.
|
|
|
|
Cookies are stored client-side and sent with every subsequent
|
|
request that matches the domain and path for which they were
|
|
stored, until they expire. This can create a non-negligible
|
|
cost.
|
|
|
|
Cookies should not be considered secure. They are stored on
|
|
the user's computer in plain text, and can be read by any
|
|
program. They can also be read by proxies when using clear
|
|
connections. Always validate the value before using it,
|
|
and never store any sensitive information inside it.
|
|
|
|
Cookies set by the server are only available in requests
|
|
following the client reception of the response containing
|
|
them.
|
|
|
|
Cookies may be sent repeatedly. This is often useful to
|
|
update the expiration time and avoid losing a cookie.
|
|
|
|
=== Setting cookies
|
|
|
|
// @todo So I am not particularly happy about set_resp_cookie/4
|
|
// having Opts as a *third* argument, instead of the *last* like
|
|
// all other functions that come with an Opts argument. We will
|
|
// probably need to change this before 2.0.
|
|
|
|
By default cookies are defined for the duration of the session:
|
|
|
|
[source,erlang]
|
|
SessionID = generate_session_id(),
|
|
Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, Req0).
|
|
|
|
They can also be set for a duration in seconds:
|
|
|
|
[source,erlang]
|
|
----
|
|
SessionID = generate_session_id(),
|
|
Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID,
|
|
#{max_age => 3600}, Req0).
|
|
----
|
|
|
|
To delete cookies, set `max_age` to 0:
|
|
|
|
[source,erlang]
|
|
----
|
|
SessionID = generate_session_id(),
|
|
Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID,
|
|
#{max_age => 0}, Req0).
|
|
----
|
|
|
|
To restrict cookies to a specific domain and path, the options
|
|
of the same name can be used:
|
|
|
|
[source,erlang]
|
|
----
|
|
Req = cowboy_req:set_resp_cookie(<<"inaccount">>, <<"1">>,
|
|
#{domain => "my.example.org", path => "/account"}, Req0).
|
|
----
|
|
|
|
Cookies will be sent with requests to this domain and all
|
|
its subdomains, and to resources on this path or deeper
|
|
in the path hierarchy.
|
|
|
|
To restrict cookies to secure channels (typically resources
|
|
available over HTTPS):
|
|
|
|
[source,erlang]
|
|
----
|
|
SessionID = generate_session_id(),
|
|
Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID,
|
|
#{secure => true}, Req0).
|
|
----
|
|
|
|
To prevent client-side scripts from accessing a cookie:
|
|
|
|
[source,erlang]
|
|
----
|
|
SessionID = generate_session_id(),
|
|
Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID,
|
|
#{http_only => true}, Req0).
|
|
----
|
|
|
|
Cookies may also be set client-side, for example using
|
|
Javascript.
|
|
|
|
=== Reading cookies
|
|
|
|
The client only ever sends back the cookie name and value.
|
|
All other options that can be set are never sent back.
|
|
|
|
Cowboy provides two functions for reading cookies. Both
|
|
involve parsing the cookie header(s) and so should not
|
|
be called repeatedly.
|
|
|
|
You can get all cookies as a key/value list:
|
|
|
|
[source,erlang]
|
|
Cookies = cowboy_req:parse_cookies(Req),
|
|
{_, Lang} = lists:keyfind(<<"lang">>, 1, Cookies).
|
|
|
|
Or you can perform a match against cookies and retrieve
|
|
only the ones you need, while at the same time doing
|
|
any required post processing using xref:constraints[constraints].
|
|
This function returns a map:
|
|
|
|
[source,erlang]
|
|
#{id := ID, lang := Lang} = cowboy_req:match_cookies([id, lang], Req).
|
|
|
|
You can use constraints to validate the values while matching
|
|
them. The following snippet will crash if the `id` cookie is
|
|
not an integer number or if the `lang` cookie is empty. Additionally
|
|
the `id` cookie value will be converted to an integer term:
|
|
|
|
[source,erlang]
|
|
CookiesMap = cowboy_req:match_cookies([{id, int}, {lang, nonempty}], Req).
|
|
|
|
Note that if two cookies share the same name, then the map value
|
|
will be a list of the two cookie values.
|
|
|
|
A default value can be provided. The default will be used
|
|
if the `lang` cookie is not found. It will not be used if
|
|
the cookie is found but has an empty value:
|
|
|
|
[source,erlang]
|
|
#{lang := Lang} = cowboy_req:match_cookies([{lang, [], <<"en-US">>}], Req).
|
|
|
|
If no default is provided and the value is missing, an
|
|
exception is thrown.
|