diff options
author | Loïc Hoguin <[email protected]> | 2019-10-04 15:19:17 +0200 |
---|---|---|
committer | Loïc Hoguin <[email protected]> | 2019-10-04 15:19:17 +0200 |
commit | bd32d879e151ba6fa1732b4eee6cac064846e9cc (patch) | |
tree | d9605b974f102327b6c096f413d0c7b797768353 | |
parent | 6a4f901c7938a070cf7a80fdb366e17f8a300aff (diff) | |
download | cowlib-bd32d879e151ba6fa1732b4eee6cac064846e9cc.tar.gz cowlib-bd32d879e151ba6fa1732b4eee6cac064846e9cc.tar.bz2 cowlib-bd32d879e151ba6fa1732b4eee6cac064846e9cc.zip |
Add manual for cow_cookie
-rw-r--r-- | Makefile | 2 | ||||
-rw-r--r-- | README.asciidoc | 3 | ||||
-rw-r--r-- | doc/src/manual/cow_cookie.asciidoc | 78 | ||||
-rw-r--r-- | doc/src/manual/cow_cookie.parse_cookie.asciidoc | 44 | ||||
-rw-r--r-- | doc/src/manual/cow_cookie.setcookie.asciidoc | 55 | ||||
-rw-r--r-- | doc/src/manual/cowlib_app.asciidoc | 40 | ||||
-rw-r--r-- | src/cow_cookie.erl | 2 |
7 files changed, 222 insertions, 2 deletions
@@ -18,6 +18,8 @@ DIALYZER_OPTS = -Werror_handling -Wunmatched_returns LOCAL_DEPS = crypto +DOC_DEPS = asciideck + TEST_DEPS = $(if $(CI_ERLANG_MK),ci.erlang.mk) horse proper dep_horse = git https://github.com/ninenines/horse.git master diff --git a/README.asciidoc b/README.asciidoc index ee3065f..8b6a5ad 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -5,7 +5,8 @@ Cowlib is a support library for manipulating Web protocols. == Goals Cowlib provides libraries for parsing and building messages -for various Web protocols, including SPDY, HTTP and Websocket. +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. 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)] diff --git a/src/cow_cookie.erl b/src/cow_cookie.erl index b53fa35..199b64b 100644 --- a/src/cow_cookie.erl +++ b/src/cow_cookie.erl @@ -180,7 +180,7 @@ parse_cookie_error_test_() -> %% Initial binary implementation: %% * Copyright 2011 Thomas Burdick <[email protected]> --spec setcookie(iodata(), iodata(), cookie_opts()) -> iodata(). +-spec setcookie(iodata(), iodata(), cookie_opts()) -> iolist(). setcookie(Name, Value, Opts) -> nomatch = binary:match(iolist_to_binary(Name), [<<$=>>, <<$,>>, <<$;>>, <<$\s>>, <<$\t>>, <<$\r>>, <<$\n>>, <<$\013>>, <<$\014>>]), |