Convert the documentation to Asciidoc

A few small revisions were made, and Erlang.mk has been updated.

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.