From 03dac1486d72d9d84a3cb99d2040c78b25853257 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Sat, 5 Oct 2019 11:23:57 +0200
Subject: Add cowboy_req:filter_cookies/2

---
 doc/src/manual/cowboy_req.asciidoc                |  1 +
 doc/src/manual/cowboy_req.filter_cookies.asciidoc | 70 +++++++++++++++++++++++
 2 files changed, 71 insertions(+)
 create mode 100644 doc/src/manual/cowboy_req.filter_cookies.asciidoc

(limited to 'doc/src/manual')

diff --git a/doc/src/manual/cowboy_req.asciidoc b/doc/src/manual/cowboy_req.asciidoc
index ca99f9f..f6f4127 100644
--- a/doc/src/manual/cowboy_req.asciidoc
+++ b/doc/src/manual/cowboy_req.asciidoc
@@ -53,6 +53,7 @@ Processed request:
 * link:man:cowboy_req:parse_qs(3)[cowboy_req:parse_qs(3)] - Parse the query string
 * link:man:cowboy_req:match_qs(3)[cowboy_req:match_qs(3)] - Match the query string against constraints
 * link:man:cowboy_req:parse_header(3)[cowboy_req:parse_header(3)] - Parse the given HTTP header
+* link:man:cowboy_req:filter_cookies(3)[cowboy_req:filter_cookies(3)] - Filter cookie headers
 * link:man:cowboy_req:parse_cookies(3)[cowboy_req:parse_cookies(3)] - Parse cookie headers
 * link:man:cowboy_req:match_cookies(3)[cowboy_req:match_cookies(3)] - Match cookies against constraints
 * link:man:cowboy_req:binding(3)[cowboy_req:binding(3)] - Access a value bound from the route
diff --git a/doc/src/manual/cowboy_req.filter_cookies.asciidoc b/doc/src/manual/cowboy_req.filter_cookies.asciidoc
new file mode 100644
index 0000000..20d0a0c
--- /dev/null
+++ b/doc/src/manual/cowboy_req.filter_cookies.asciidoc
@@ -0,0 +1,70 @@
+= cowboy_req:filter_cookies(3)
+
+== Name
+
+cowboy_req:filter_cookies - Filter cookie headers
+
+== Description
+
+[source,erlang]
+----
+filter_cookies(Names, Req) -> Req
+
+Names :: [atom() | binary()]
+----
+
+Filter cookie headers.
+
+This function is meant to be used before attempting to parse
+or match cookies in order to remove cookies that are not
+relevant and are potentially malformed. Because Cowboy by
+default crashes on malformed cookies, this function allows
+processing requests that would otherwise result in a 400
+error.
+
+Malformed cookies are unfortunately fairly common due to
+the string-based interface provided by browsers and this
+function provides a middle ground between Cowboy's strict
+behavior and chaotic real world use cases.
+
+Note that there may still be crashes even after filtering
+cookies because this function does not correct malformed
+values. Cookies that have malformed values should probably
+be unset in an error response or in a redirect.
+
+This function can be called even if there are no cookies
+in the request.
+
+== Arguments
+
+Names::
+
+The cookies that should be kept.
+
+Req::
+
+The Req object.
+
+== Return value
+
+The Req object is returned with its cookie header value
+filtered.
+
+== Changelog
+
+* *2.7*: Function introduced.
+
+== Examples
+
+.Filter then parse cookies
+[source,erlang]
+----
+Req = cowboy_req:filter_cookies([session_id, token], Req0),
+Cookies = cowboy_req:parse_cookies(Req).
+----
+
+== See also
+
+link:man:cowboy_req(3)[cowboy_req(3)],
+link:man:cowboy_req:parse_cookies(3)[cowboy_req:parse_cookies(3)],
+link:man:cowboy_req:match_cookies(3)[cowboy_req:match_cookies(3)]
-- 
cgit v1.2.3