aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2020-03-19 14:56:49 +0100
committerLoïc Hoguin <[email protected]>2020-03-19 14:56:49 +0100
commit8a9f7dcb43c0b5e4d11bc63bfd0f23e2740fac7e (patch)
treeadc7f19cfa10cad2b6030eff73a02f5eec798554 /doc/src/manual
parentf017f8a0ecbffd5033d9ab49bf180186f7a523a7 (diff)
downloadcowlib-8a9f7dcb43c0b5e4d11bc63bfd0f23e2740fac7e.tar.gz
cowlib-8a9f7dcb43c0b5e4d11bc63bfd0f23e2740fac7e.tar.bz2
cowlib-8a9f7dcb43c0b5e4d11bc63bfd0f23e2740fac7e.zip
Document the new cow_cookie functions
Diffstat (limited to 'doc/src/manual')
-rw-r--r--doc/src/manual/cow_cookie.asciidoc28
-rw-r--r--doc/src/manual/cow_cookie.cookie.asciidoc45
-rw-r--r--doc/src/manual/cow_cookie.parse_cookie.asciidoc2
-rw-r--r--doc/src/manual/cow_cookie.parse_set_cookie.asciidoc57
-rw-r--r--doc/src/manual/cow_cookie.setcookie.asciidoc4
5 files changed, 135 insertions, 1 deletions
diff --git a/doc/src/manual/cow_cookie.asciidoc b/doc/src/manual/cow_cookie.asciidoc
index 2c33104..257d01e 100644
--- a/doc/src/manual/cow_cookie.asciidoc
+++ b/doc/src/manual/cow_cookie.asciidoc
@@ -12,10 +12,33 @@ 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:parse_set_cookie(3)[cow_cookie:parse_set_cookie(3)] - Parse a set-cookie header
+* link:man:cow_cookie:cookie(3)[cow_cookie:cookie(3)] - Generate a cookie header
* link:man:cow_cookie:setcookie(3)[cow_cookie:setcookie(3)] - Generate a set-cookie header
== Types
+=== cookie_attrs()
+
+[source,erlang]
+----
+cookie_attrs() :: #{
+ expires => calendar:datetime(),
+ max_age => calendar:datetime(),
+ domain => binary(),
+ path => binary(),
+ secure => true,
+ http_only => true,
+ same_site => strict | lax
+}
+----
+
+Cookie attributes parsed from the set-cookie header.
+The attributes must be passed as-is to a cookie store
+engine for processing, along with the cookie name and value.
+More information about the attributes can be found in
+https://tools.ietf.org/html/rfc6265[RFC 6265].
+
=== cookie_opts()
[source,erlang]
@@ -72,6 +95,11 @@ Whether the cookie should be sent only on secure channels
integrity of the cookie, only its confidentiality during
transfer. By default there are no restrictions.
+== Changelog
+
+* *2.9*: The `cookie_attrs` type was added.
+* *1.0*: Module introduced.
+
== See also
link:man:cowlib(7)[cowlib(7)],
diff --git a/doc/src/manual/cow_cookie.cookie.asciidoc b/doc/src/manual/cow_cookie.cookie.asciidoc
new file mode 100644
index 0000000..c40d66b
--- /dev/null
+++ b/doc/src/manual/cow_cookie.cookie.asciidoc
@@ -0,0 +1,45 @@
+= cow_cookie:cookie(3)
+
+== Name
+
+cow_cookie:cookie - Generate a cookie header
+
+== Description
+
+[source,erlang]
+----
+cookie(Cookies) -> iolist()
+
+Cookies :: [{Name :: iodata(), Value :: iodata()}]
+----
+
+Generate a cookie header.
+
+== Arguments
+
+Cookies::
+
+A list of pairs of cookie name and value.
+
+== Return value
+
+An iolist with the generated cookie header value.
+
+== Changelog
+
+* *2.9*: Function introduced.
+
+== Examples
+
+.Generate a cookie header
+[source,erlang]
+----
+Cookie = cow_cookie:cookie([{<<"sessionid">>, ID}]).
+----
+
+== See also
+
+link:man:cow_cookie(3)[cow_cookie(3)],
+link:man:cow_cookie:parse_cookie(3)[cow_cookie:parse_cookie(3)],
+link:man:cow_cookie:parse_set_cookie(3)[cow_cookie:parse_set_cookie(3)],
+link:man:cow_cookie:setcookie(3)[cow_cookie:setcookie(3)]
diff --git a/doc/src/manual/cow_cookie.parse_cookie.asciidoc b/doc/src/manual/cow_cookie.parse_cookie.asciidoc
index 2975932..2f27d7d 100644
--- a/doc/src/manual/cow_cookie.parse_cookie.asciidoc
+++ b/doc/src/manual/cow_cookie.parse_cookie.asciidoc
@@ -45,4 +45,6 @@ Cookies = cow_cookie:parse_cookie(CookieHd).
== See also
link:man:cow_cookie(3)[cow_cookie(3)],
+link:man:cow_cookie:parse_set_cookie(3)[cow_cookie:parse_set_cookie(3)],
+link:man:cow_cookie:cookie(3)[cow_cookie:cookie(3)],
link:man:cow_cookie:setcookie(3)[cow_cookie:setcookie(3)]
diff --git a/doc/src/manual/cow_cookie.parse_set_cookie.asciidoc b/doc/src/manual/cow_cookie.parse_set_cookie.asciidoc
new file mode 100644
index 0000000..6a49dde
--- /dev/null
+++ b/doc/src/manual/cow_cookie.parse_set_cookie.asciidoc
@@ -0,0 +1,57 @@
+= cow_cookie:parse_set_cookie(3)
+
+== Name
+
+cow_cookie:parse_set_cookie - Parse a set-cookie header
+
+== Description
+
+[source,erlang]
+----
+parse_set_cookie(SetCookie :: binary())
+ -> {ok, Name, Value, Attrs} | ignore
+
+Name :: binary()
+Value :: binary()
+Attrs :: cow_cookie:cookie_attrs()
+----
+
+Parse a set-cookie header.
+
+== Arguments
+
+SetCookie::
+
+The set-cookie header value.
+
+== Return value
+
+An `ok` tuple with the cookie name, value and attributes
+is returned on success.
+
+An atom `ignore` is returned when the cookie has both
+an empty name and an empty value, and must be ignored.
+
+== Changelog
+
+* *2.9*: Function introduced.
+
+== Examples
+
+.Parse a cookie header
+[source,erlang]
+----
+case cow_cookie:parse_set_cookie(SetCookieHd) of
+ {ok, Name, Value, Attrs} ->
+ cookie_engine_set_cookie(Name, Value, Attrs);
+ ignore ->
+ do_nothing()
+end.
+----
+
+== See also
+
+link:man:cow_cookie(3)[cow_cookie(3)],
+link:man:cow_cookie:parse_cookie(3)[cow_cookie:parse_cookie(3)],
+link:man:cow_cookie:cookie(3)[cow_cookie: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
index 96ddcac..d600a07 100644
--- a/doc/src/manual/cow_cookie.setcookie.asciidoc
+++ b/doc/src/manual/cow_cookie.setcookie.asciidoc
@@ -52,4 +52,6 @@ SetCookie = cow_cookie:setcookie(<<"sessionid">>, ID, #{
== See also
link:man:cow_cookie(3)[cow_cookie(3)],
-link:man:cow_cookie:parse_cookie(3)[cow_cookie:parse_cookie(3)]
+link:man:cow_cookie:parse_cookie(3)[cow_cookie:parse_cookie(3)],
+link:man:cow_cookie:parse_set_cookie(3)[cow_cookie:parse_set_cookie(3)],
+link:man:cow_cookie:cookie(3)[cow_cookie:cookie(3)]