From bd32d879e151ba6fa1732b4eee6cac064846e9cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Fri, 4 Oct 2019 15:19:17 +0200 Subject: Add manual for cow_cookie --- doc/src/manual/cow_cookie.asciidoc | 78 +++++++++++++++++++++++++ doc/src/manual/cow_cookie.parse_cookie.asciidoc | 44 ++++++++++++++ doc/src/manual/cow_cookie.setcookie.asciidoc | 55 +++++++++++++++++ doc/src/manual/cowlib_app.asciidoc | 40 +++++++++++++ 4 files changed, 217 insertions(+) create mode 100644 doc/src/manual/cow_cookie.asciidoc create mode 100644 doc/src/manual/cow_cookie.parse_cookie.asciidoc create mode 100644 doc/src/manual/cow_cookie.setcookie.asciidoc create mode 100644 doc/src/manual/cowlib_app.asciidoc (limited to 'doc') diff --git a/doc/src/manual/cow_cookie.asciidoc b/doc/src/manual/cow_cookie.asciidoc new file mode 100644 index 0000000..0717299 --- /dev/null +++ b/doc/src/manual/cow_cookie.asciidoc @@ -0,0 +1,78 @@ += cow_cookie(3) + +== Name + +cow_cookie - Cookies + +== Description + +The module `cow_cookie` provides functions for parsing +and manipulating cookie headers. + +== Exports + +* link:man:cow_cookie:parse_cookie(3)[cow_cookie:parse_cookie(3)] - Parse a cookie header +* link:man:cow_cookie:setcookie(3)[cow_cookie:setcookie(3)] - Generate a set-cookie header + +== Types + +=== cookie_opts() + +[source,erlang] +---- +cookie_opts() :: [Option] + +Option :: {domain, binary()} + | {http_only, boolean()} + | {max_age, non_neg_integer()} + | {path, binary()} + | {same_site, lax | strict} + | {secure, boolean()} +---- + +Options for the set-cookie header. They are added to the +header as attributes. More information about the options +can be found in https://tools.ietf.org/html/rfc6265[RFC 6265]. + +The following options are defined: + +domain:: + +Hosts to which the cookie will be sent. By default it will +only be sent to the origin server. + +http_only:: + +Whether the cookie should be restricted to HTTP requests, or +it should also be exposed to other APIs, for example Javascript. +By default there are no restrictions. + +max_age:: + +Maximum lifetime of the cookie, in seconds. By default the +cookie is kept for the duration of the session. + +path:: + +Path to which the cookie will be sent. By default it will +be sent to the current "directory" of the effective request URI. + +same_site:: + +Whether the cookie should be sent along with cross-site +requests. This header is currently non-standard but is in +the process of being standardized. Please refer to the +https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7[RFC 6265 (bis) draft] +for details. + +secure:: + +Whether the cookie should be sent only on secure channels +(for example TLS). Note that this does not guarantee the +integrity of the cookie, only its confidentiality during +transfer. By default there are no restrictions. + +== See also + +link:man:cowlib(7)[cowlib(7)], +https://tools.ietf.org/html/rfc6265[RFC 6265] diff --git a/doc/src/manual/cow_cookie.parse_cookie.asciidoc b/doc/src/manual/cow_cookie.parse_cookie.asciidoc new file mode 100644 index 0000000..0b7393e --- /dev/null +++ b/doc/src/manual/cow_cookie.parse_cookie.asciidoc @@ -0,0 +1,44 @@ += cow_cookie:parse_cookie(3) + +== Name + +cow_cookie:parse_cookie - Parse a cookie header + +== Description + +[source,erlang] +---- +parse_cookie(Cookie :: binary()) + -> [{binary(), binary()}] +---- + +Parse a cookie header. + +== Arguments + +Cookie:: + +The cookie header value. + +== Return value + +A list of cookie name/value pairs is returned on success. + +An exception is thrown in the event of a parse error. + +== Changelog + +* *1.0*: Function introduced. + +== Examples + +.Parse a cookie header +[source,erlang] +---- +Cookies = cow_cookie:parse_cookie(CookieHd). +---- + +== See also + +link:man:cow_cookie(3)[cow_cookie(3)], +link:man:cow_cookie:setcookie(3)[cow_cookie:setcookie(3)] diff --git a/doc/src/manual/cow_cookie.setcookie.asciidoc b/doc/src/manual/cow_cookie.setcookie.asciidoc new file mode 100644 index 0000000..ab2d466 --- /dev/null +++ b/doc/src/manual/cow_cookie.setcookie.asciidoc @@ -0,0 +1,55 @@ += cow_cookie:setcookie(3) + +== Name + +cow_cookie:setcookie - Generate a set-cookie header + +== Description + +[source,erlang] +---- +setcookie(Name :: iodata(), + Value :: iodata(), + Opts :: cow_cookie:cookie_opts()) + -> iolist() +---- + +Generate a set-cookie header. + +== Arguments + +Name:: + +Cookie name. + +Value:: + +Cookie value. + +Opts:: + +Options added to the set-cookie header as attributes. + +== Return value + +An iolist with the generated set-cookie header value. + +== Changelog + +* *1.0*: Function introduced. + +== Examples + +.Generate a set-cookie header +[source,erlang] +---- +SetCookie = cow_cookie:setcookie(<<"sessionid">>, ID, #{ + http_only => true, + secure => true +}). +---- + +== See also + +link:man:cow_cookie(3)[cow_cookie(3)], +link:man:cow_cookie:parse_cookie(3)[cow_cookie:parse_cookie(3)] diff --git a/doc/src/manual/cowlib_app.asciidoc b/doc/src/manual/cowlib_app.asciidoc new file mode 100644 index 0000000..5e659d2 --- /dev/null +++ b/doc/src/manual/cowlib_app.asciidoc @@ -0,0 +1,40 @@ += cowlib(7) + +== Name + +cowlib - Support library for manipulating Web protocols + +== Description + +Cowlib provides libraries for parsing and building messages +for various Web protocols, including HTTP/1.1, HTTP/2 and +Websocket. + +It is optimized for completeness rather than speed. No value +is ignored, they are all returned. + +== Modules + +* link:man:cow_cookie(3)[cow_cookie(3)] - Cookies + +== Dependencies + +* crypto - Crypto functions + +All these applications must be started before the `cowlib` +application. To start Cowlib and all dependencies at once: + +[source,erlang] +---- +{ok, _} = application:ensure_all_started(cowlib). +---- + +== Environment + +The `cowlib` application does not define any application +environment configuration parameters. + +== See also + +link:man:cowboy(7)[cowboy(7)], +link:man:gun(7)[gun(7)] -- cgit v1.2.3