From 4b385749f2aab90b5c7e44e844159c0221a8790d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Fri, 7 Sep 2018 13:56:12 +0200 Subject: Add cowboy_req:read_and_match_urlencoded_body/2,3 --- doc/src/manual/cowboy_req.asciidoc | 1 + ...boy_req.read_and_match_urlencoded_body.asciidoc | 148 +++++++++++++++++++++ doc/src/manual/cowboy_req.read_body.asciidoc | 1 + doc/src/manual/cowboy_req.read_part.asciidoc | 1 + doc/src/manual/cowboy_req.read_part_body.asciidoc | 1 + .../cowboy_req.read_urlencoded_body.asciidoc | 1 + 6 files changed, 153 insertions(+) create mode 100644 doc/src/manual/cowboy_req.read_and_match_urlencoded_body.asciidoc (limited to 'doc') diff --git a/doc/src/manual/cowboy_req.asciidoc b/doc/src/manual/cowboy_req.asciidoc index 309aedf..2758e8f 100644 --- a/doc/src/manual/cowboy_req.asciidoc +++ b/doc/src/manual/cowboy_req.asciidoc @@ -66,6 +66,7 @@ Request body: * link:man:cowboy_req:body_length(3)[cowboy_req:body_length(3)] - Body length * link:man:cowboy_req:read_body(3)[cowboy_req:read_body(3)] - Read the request body * link:man:cowboy_req:read_urlencoded_body(3)[cowboy_req:read_urlencoded_body(3)] - Read and parse a urlencoded request body +* link:man:cowboy_req:read_and_match_urlencoded_body(3)[cowboy_req:read_and_match_urlencoded_body(3)] - Read, parse and match a urlencoded request body against constraints * link:man:cowboy_req:read_part(3)[cowboy_req:read_part(3)] - Read the next multipart headers * link:man:cowboy_req:read_part_body(3)[cowboy_req:read_part_body(3)] - Read the current part's body diff --git a/doc/src/manual/cowboy_req.read_and_match_urlencoded_body.asciidoc b/doc/src/manual/cowboy_req.read_and_match_urlencoded_body.asciidoc new file mode 100644 index 0000000..aa2704c --- /dev/null +++ b/doc/src/manual/cowboy_req.read_and_match_urlencoded_body.asciidoc @@ -0,0 +1,148 @@ += cowboy_req:read_and_match_urlencoded_body(3) + +== Name + +cowboy_req:read_and_match_urlencoded_body - Read, parse +and match a urlencoded request body against constraints + +== Description + +[source,erlang] +---- +read_and_match_urlencoded_body(Fields, Req) + -> read_and_match_urlencoded_body(Fields, Req, #{}) + +read_and_match_urlencoded_body(Fields, Req, Opts) + -> {ok, Body, Req} + +Fields :: cowboy:fields() +Req :: cowboy_req:req() +Opts :: cowboy_req:read_body_opts() +Body :: #{atom() => any()} +---- + +Read, parse and match a urlencoded request body against +constraints. + +This function reads the request body and parses it as +`application/x-www-form-urlencoded`. It then applies +the given field constraints to the urlencoded data +and returns the result as a map. + +The urlencoded media type is used by Web browsers when +submitting HTML forms using the POST method. + +Cowboy will only return the values specified +in the fields list, and ignore all others. Fields can be +either the key requested; the key along with a list of +constraints; or the key, a list of constraints and a +default value in case the key is missing. + +This function will crash if the key is missing and no +default value is provided. This function will also crash +if a constraint fails. + +The key must be provided as an atom. The key of the +returned map will be that atom. The value may be converted +through the use of constraints, making this function able +to extract, validate and convert values all in one step. + +Cowboy needs to read the full body before parsing. By default +it will read bodies of size up to 64KB. It is possible to +provide options to read larger bodies if required. + +Cowboy will automatically handle protocol details including +the expect header, chunked transfer-encoding and others. + +Once the body has been read, Cowboy sets the content-length +header if it was not previously provided. + +This function can only be called once. Calling it again will +result in undefined behavior. + +== Arguments + +Fields:: + +Fields to retrieve from the urlencoded body. ++ +See link:man:cowboy(3)[cowboy(3)] for a complete description. + +Req:: + +The Req object. + +Opts:: + +A map of body reading options. Please refer to +link:man:cowboy_req:read_body(3)[cowboy_req:read_body(3)] +for details about each option. ++ +This function defaults the `length` to 64KB and the `period` +to 5 seconds. + +== Return value + +An `ok` tuple is returned. + +Desired values are returned as a map. The key is the atom +that was given in the list of fields, and the value is the +optionally converted value after applying constraints. + +The map contains the same keys that were given in the fields. + +An exception is triggered when the match fails. + +The Req object returned in the tuple must be used from that point +onward. It contains a more up to date representation of the request. +For example it may have an added content-length header once the +body has been read. + +== Changelog + +* *2.5*: Function introduced. + +== Examples + +.Match fields +[source,erlang] +---- +%% ID and Lang are binaries. +#{id := ID, lang := Lang} + = cowboy_req:read_and_match_urlencoded_body( + [id, lang], Req). +---- + +.Match fields and apply constraints +[source,erlang] +---- +%% ID is an integer and Lang a non-empty binary. +#{id := ID, lang := Lang} + = cowboy_req:read_and_match_urlencoded_body( + [{id, int}, {lang, nonempty}], Req). +---- + +.Match fields with default values +[source,erlang] +---- +#{lang := Lang} + = cowboy_req:read_and_match_urlencoded_body( + [{lang, [], <<"en-US">>}], Req). +---- + +.Allow large urlencoded bodies +[source,erlang] +---- +{ok, Body, Req} = cowboy_req:read_and_match_urlencoded_body( + Fields, Req0, #{length => 1000000}). +---- + +== See also + +link:man:cowboy_req(3)[cowboy_req(3)], +link:man:cowboy_req:has_body(3)[cowboy_req:has_body(3)], +link:man:cowboy_req:body_length(3)[cowboy_req:body_length(3)], +link:man:cowboy_req:read_body(3)[cowboy_req:read_body(3)], +link:man:cowboy_req:read_urlencoded_body(3)[cowboy_req:read_urlencoded_body(3)], +link:man:cowboy_req:read_part(3)[cowboy_req:read_part(3)], +link:man:cowboy_req:read_part_body(3)[cowboy_req:read_part_body(3)] diff --git a/doc/src/manual/cowboy_req.read_body.asciidoc b/doc/src/manual/cowboy_req.read_body.asciidoc index 729b2f0..2b87405 100644 --- a/doc/src/manual/cowboy_req.read_body.asciidoc +++ b/doc/src/manual/cowboy_req.read_body.asciidoc @@ -112,5 +112,6 @@ link:man:cowboy_req(3)[cowboy_req(3)], link:man:cowboy_req:has_body(3)[cowboy_req:has_body(3)], link:man:cowboy_req:body_length(3)[cowboy_req:body_length(3)], link:man:cowboy_req:read_urlencoded_body(3)[cowboy_req:read_urlencoded_body(3)], +link:man:cowboy_req:read_and_match_urlencoded_body(3)[cowboy_req:read_and_match_urlencoded_body(3)], link:man:cowboy_req:read_part(3)[cowboy_req:read_part(3)], link:man:cowboy_req:read_part_body(3)[cowboy_req:read_part_body(3)] diff --git a/doc/src/manual/cowboy_req.read_part.asciidoc b/doc/src/manual/cowboy_req.read_part.asciidoc index ceed72a..9123b2e 100644 --- a/doc/src/manual/cowboy_req.read_part.asciidoc +++ b/doc/src/manual/cowboy_req.read_part.asciidoc @@ -131,4 +131,5 @@ link:man:cowboy_req:has_body(3)[cowboy_req:has_body(3)], link:man:cowboy_req:body_length(3)[cowboy_req:body_length(3)], link:man:cowboy_req:read_body(3)[cowboy_req:read_body(3)], link:man:cowboy_req:read_urlencoded_body(3)[cowboy_req:read_urlencoded_body(3)], +link:man:cowboy_req:read_and_match_urlencoded_body(3)[cowboy_req:read_and_match_urlencoded_body(3)], link:man:cowboy_req:read_part_body(3)[cowboy_req:read_part_body(3)] diff --git a/doc/src/manual/cowboy_req.read_part_body.asciidoc b/doc/src/manual/cowboy_req.read_part_body.asciidoc index 3a1af2f..dc634f3 100644 --- a/doc/src/manual/cowboy_req.read_part_body.asciidoc +++ b/doc/src/manual/cowboy_req.read_part_body.asciidoc @@ -97,4 +97,5 @@ link:man:cowboy_req:has_body(3)[cowboy_req:has_body(3)], link:man:cowboy_req:body_length(3)[cowboy_req:body_length(3)], link:man:cowboy_req:read_body(3)[cowboy_req:read_body(3)], link:man:cowboy_req:read_urlencoded_body(3)[cowboy_req:read_urlencoded_body(3)], +link:man:cowboy_req:read_and_match_urlencoded_body(3)[cowboy_req:read_and_match_urlencoded_body(3)], link:man:cowboy_req:read_part(3)[cowboy_req:read_part(3)] diff --git a/doc/src/manual/cowboy_req.read_urlencoded_body.asciidoc b/doc/src/manual/cowboy_req.read_urlencoded_body.asciidoc index 3b65fcf..e897a69 100644 --- a/doc/src/manual/cowboy_req.read_urlencoded_body.asciidoc +++ b/doc/src/manual/cowboy_req.read_urlencoded_body.asciidoc @@ -90,5 +90,6 @@ link:man:cowboy_req(3)[cowboy_req(3)], link:man:cowboy_req:has_body(3)[cowboy_req:has_body(3)], link:man:cowboy_req:body_length(3)[cowboy_req:body_length(3)], link:man:cowboy_req:read_body(3)[cowboy_req:read_body(3)], +link:man:cowboy_req:read_and_match_urlencoded_body(3)[cowboy_req:read_and_match_urlencoded_body(3)], link:man:cowboy_req:read_part(3)[cowboy_req:read_part(3)], link:man:cowboy_req:read_part_body(3)[cowboy_req:read_part_body(3)] -- cgit v1.2.3