aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/manual')
-rw-r--r--doc/src/manual/cow_cookie.asciidoc78
-rw-r--r--doc/src/manual/cow_cookie.parse_cookie.asciidoc44
-rw-r--r--doc/src/manual/cow_cookie.setcookie.asciidoc55
-rw-r--r--doc/src/manual/cowlib_app.asciidoc40
4 files changed, 217 insertions, 0 deletions
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)]