From 4023e7f4e429179fd9c2cce4487c33646c6bd327 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Thu, 14 Jan 2016 13:35:25 +0100 Subject: Convert the documentation to Asciidoc A few small revisions were made, and Erlang.mk has been updated. --- doc/src/guide/cookies.asciidoc | 163 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 doc/src/guide/cookies.asciidoc (limited to 'doc/src/guide/cookies.asciidoc') diff --git a/doc/src/guide/cookies.asciidoc b/doc/src/guide/cookies.asciidoc new file mode 100644 index 0000000..6068db3 --- /dev/null +++ b/doc/src/guide/cookies.asciidoc @@ -0,0 +1,163 @@ +[[cookies]] +== Using cookies + +Cookies are a mechanism allowing applications to maintain +state on top of the stateless HTTP protocol. + +Cowboy provides facilities for handling cookies. It is highly +recommended to use them instead of writing your own, as the +implementation of cookies can vary greatly between clients. + +Cookies are stored client-side and sent with every subsequent +request that matches the domain and path for which they were +stored, including requests for static files. For this reason +they can incur a cost which must be taken in consideration. + +Also consider that, regardless of the options used, cookies +are not to be trusted. They may be read and modified by any +program on the user's computer, but also by proxies. You +should always validate cookie values before using them. Do +not store any sensitive information in cookies either. + +When explicitly setting the domain, the cookie will be sent +for the domain and all subdomains from that domain. Otherwise +the current domain will be used. The same is true for the +path. + +When the server sets cookies, they will only be available +for requests that are sent after the client receives the +response. + +Cookies are sent in HTTP headers, therefore they must have +text values. It is your responsibility to encode any other +data type. Also note that cookie names are de facto case +sensitive. + +Cookies can be set for the client session (which generally +means until the browser is closed), or it can be set for +a number of seconds. Once it expires, or when the server +says the cookie must exist for up to 0 seconds, the cookie +is deleted by the client. To avoid this while the user +is browsing your site, you should set the cookie for +every request, essentially resetting the expiration time. + +Cookies can be restricted to secure channels. This typically +means that such a cookie will only be sent over HTTPS, +and that it will only be available by client-side scripts +that run from HTTPS webpages. + +Finally, cookies can be restricted to HTTP and HTTPS requests, +essentially disabling their access from client-side scripts. + +=== Setting cookies + +By default, cookies you set are defined for the session. + +[source,erlang] +SessionID = generate_session_id(), +Req2 = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [], Req). + +You can also make them expire at a specific point in the +future. + +[source,erlang] +---- +SessionID = generate_session_id(), +Req2 = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [ + {max_age, 3600} +], Req). +---- + +You can delete cookies that have already been set. The value +is ignored. + +[source,erlang] +---- +Req2 = cowboy_req:set_resp_cookie(<<"sessionid">>, <<>>, [ + {max_age, 0} +], Req). +---- + +You can restrict them to a specific domain and path. +For example, the following cookie will be set for the domain +`my.example.org` and all its subdomains, but only on the path +`/account` and all its subdirectories. + +[source,erlang] +---- +Req2 = cowboy_req:set_resp_cookie(<<"inaccount">>, <<"1">>, [ + {domain, "my.example.org"}, + {path, "/account"} +], Req). +---- + +You can restrict the cookie to secure channels, typically HTTPS. + +[source,erlang] +---- +SessionID = generate_session_id(), +Req2 = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [ + {secure, true} +], Req). +---- + +You can restrict the cookie to client-server communication +only. Such a cookie will not be available to client-side scripts. + +[source,erlang] +---- +SessionID = generate_session_id(), +Req2 = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [ + {http_only, true} +], Req). +---- + +Cookies may also be set client-side, for example using +Javascript. + +=== Reading cookies + +As we said, the client sends cookies with every request. +But unlike the server, the client only sends the cookie +name and value. + +Cowboy provides two different ways to read cookies. You +can either parse them as a list of key/value pairs, or +match them into a map, optionally applying constraints +to the values or providing a default if they are missing. + +You can parse the cookies and then use standard library +functions to access individual values. + +[source,erlang] +Cookies = cowboy_req:parse_cookies(Req), +{_, Lang} = lists:keyfind(<<"lang">>, 1, Cookies). + +You can match the cookies into 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, saving +you a conversion step. + +[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. + +Read more about xref:constraints[constraints]. + +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, the +query string is deemed invalid and the process will crash. -- cgit v1.2.3