From 48f39402181d959cad88cb3f460210c007169f50 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 12 May 2021 11:13:47 +0200 Subject: Cowboy 2.9.0 --- docs/en/cowboy/2.9/guide/cookies.asciidoc | 139 ++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 docs/en/cowboy/2.9/guide/cookies.asciidoc (limited to 'docs/en/cowboy/2.9/guide/cookies.asciidoc') diff --git a/docs/en/cowboy/2.9/guide/cookies.asciidoc b/docs/en/cowboy/2.9/guide/cookies.asciidoc new file mode 100644 index 00000000..4825031b --- /dev/null +++ b/docs/en/cowboy/2.9/guide/cookies.asciidoc @@ -0,0 +1,139 @@ +[[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 + +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, Req0, + #{max_age => 3600}). +---- + +To delete cookies, set `max_age` to 0: + +[source,erlang] +---- +SessionID = generate_session_id(), +Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, Req0, + #{max_age => 0}). +---- + +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">>, Req0, + #{domain => "my.example.org", path => "/account"}). +---- + +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, Req0, + #{secure => true}). +---- + +To prevent client-side scripts from accessing a cookie: + +[source,erlang] +---- +SessionID = generate_session_id(), +Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, Req0, + #{http_only => true}). +---- + +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. -- cgit v1.2.3