From c528d9b0f7698b5b901cbc8841a96fb4bd38aba9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Fri, 2 Dec 2016 16:50:31 +0100 Subject: Add the man pages for body reading functions [ci skip] --- doc/src/manual/cowboy_req.asciidoc | 4 +- doc/src/manual/cowboy_req.body_length.asciidoc | 51 ++++++++ doc/src/manual/cowboy_req.has_body.asciidoc | 45 +++++++ doc/src/manual/cowboy_req.read_body.asciidoc | 116 ++++++++++++++++++ doc/src/manual/cowboy_req.read_part.asciidoc | 134 +++++++++++++++++++++ doc/src/manual/cowboy_req.read_part_body.asciidoc | 100 +++++++++++++++ .../cowboy_req.read_urlencoded_body.asciidoc | 94 +++++++++++++++ 7 files changed, 542 insertions(+), 2 deletions(-) create mode 100644 doc/src/manual/cowboy_req.body_length.asciidoc create mode 100644 doc/src/manual/cowboy_req.has_body.asciidoc create mode 100644 doc/src/manual/cowboy_req.read_body.asciidoc create mode 100644 doc/src/manual/cowboy_req.read_part.asciidoc create mode 100644 doc/src/manual/cowboy_req.read_part_body.asciidoc create mode 100644 doc/src/manual/cowboy_req.read_urlencoded_body.asciidoc (limited to 'doc/src') diff --git a/doc/src/manual/cowboy_req.asciidoc b/doc/src/manual/cowboy_req.asciidoc index b1d97ff..c7c0e58 100644 --- a/doc/src/manual/cowboy_req.asciidoc +++ b/doc/src/manual/cowboy_req.asciidoc @@ -61,8 +61,8 @@ 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_part(3)[cowboy_req:read_part(3)] - Read the next part of a multipart body -* link:man:cowboy_req:read_part_body(3)[cowboy_req:read_part_body(3)] - Read the current part's body in a multipart body +* 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 Response: diff --git a/doc/src/manual/cowboy_req.body_length.asciidoc b/doc/src/manual/cowboy_req.body_length.asciidoc new file mode 100644 index 0000000..057ab4c --- /dev/null +++ b/doc/src/manual/cowboy_req.body_length.asciidoc @@ -0,0 +1,51 @@ += cowboy_req:body_length(3) + +== Name + +cowboy_req:body_length - Body length + +== Description + +[source,erlang] +---- +body_length(Req :: cowboy_req:req()) -> undefined | non_neg_integer() +---- + +Return the length of the request body. + +The length is not always known before reading the body. +In those cases Cowboy will return `undefined`. The body +length is available after the body has been fully read. + +== Arguments + +Req:: + +The Req object. + +== Return value + +The length of the request body, or `undefined` if it is +not known. + +== Changelog + +* *2.0*: Only the length is returned, it is no longer wrapped in a tuple. +* *1.0*: Function introduced. + +== Examples + +.Get the body length +[source,erlang] +---- +Length = cowboy_req:body_length(Req). +---- + +== 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: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.has_body.asciidoc b/doc/src/manual/cowboy_req.has_body.asciidoc new file mode 100644 index 0000000..5e985b1 --- /dev/null +++ b/doc/src/manual/cowboy_req.has_body.asciidoc @@ -0,0 +1,45 @@ += cowboy_req:has_body(3) + +== Name + +cowboy_req:has_body - Is there a request body? + +== Description + +[source,erlang] +---- +has_body(Req :: cowboy_req:req()) -> boolean() +---- + +Return whether the request has a body. + +== Arguments + +Req:: + +The Req object. + +== Return value + +A boolean indicating whether the request has a body. + +== Changelog + +* *1.0*: Function introduced. + +== Examples + +.Ensure the request has a body +[source,erlang] +---- +true = cowboy_req:has_body(Req). +---- + +== See also + +link:man:cowboy_req(3)[cowboy_req(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 new file mode 100644 index 0000000..cb58aad --- /dev/null +++ b/doc/src/manual/cowboy_req.read_body.asciidoc @@ -0,0 +1,116 @@ += cowboy_req:read_body(3) + +== Name + +cowboy_req:read_body - Read the request body + +== Description + +[source,erlang] +---- +read_body(Req :: cowboy_req:req()) + -> read_body(Req, #{}) + +read_body(Req :: cowboy_req:req(), Opts) + -> {ok, Data :: binary(), Req} + | {more, Data :: binary(), Req} + +Opts :: cowboy_req:read_body_opts() +---- + +Read the request body. + +This function reads a chunk of the request body. A `more` tuple +is returned when more data remains to be read. Call the function +repeatedly until an `ok` tuple is returned to read the entire body. + +An `ok` tuple with empty data is returned when the request has no body, +or when calling this function again after the body has already +been read. It is therefore safe to call this function directly. +Note that the body can only be read once. + +This function reads the request body from the connection process. +The connection process is responsible for reading from the socket. +The exact behavior varies depending on the protocol. + +The options therefore are only related to the communication +between the request process and the connection process. + +Cowboy will automatically handle protocol details including +the expect header, chunked transfer-encoding and others. + +Once the body has been read fully, Cowboy sets the content-length +header if it was not previously provided. + +== Arguments + +Req:: + +The Req object. + +Opts:: + +A map of body reading options. ++ +The `length` option can be used to request smaller or bigger +chunks of data to be sent. It is a best effort approach, Cowboy +may send more data than configured on occasions. It defaults +to 8MB. ++ +The `period` indicates how long the connection process will wait +before it provides us with the data it received. It defaults +to 15 seconds. ++ +The connection process sends data to the request process when +either the `length` of data or the `period` of time is reached. ++ +The `timeout` option is a safeguard in case the connection +process becomes unresponsive. The function will crash if no +message was received in that interval. The timeout should be +larger than the period. It defaults to the period + 1 second. + +== Return value + +A `more` tuple is returned when there are more data to be read. + +An `ok` tuple is returned when there are no more data to be read, +either because this is the last chunk of data, the body has already +been read, or there was no body to begin with. + +The data is always returned as a binary. + +The Req object returned in the tuple must be used for 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.0*: Function introduced. Replaces `body/1,2`. + +== Examples + +.Read the entire body +[source,erlang] +---- +read_body(Req0, Acc) -> + case cowboy_req:read_body(Req0) of + {ok, Data, Req} -> {ok, << Acc/binary, Data/binary >>, Req}; + {more, Data, Req} -> read_body(Req, << Acc/binary, Data/binary >>) + end. +---- + +.Read the body in small chunks +[source,erlang] +---- +cowboy_req:read_body(Req, #{length => 64000}). +---- + +== 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_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_part.asciidoc b/doc/src/manual/cowboy_req.read_part.asciidoc new file mode 100644 index 0000000..0d689d8 --- /dev/null +++ b/doc/src/manual/cowboy_req.read_part.asciidoc @@ -0,0 +1,134 @@ += cowboy_req:read_part(3) + +== Name + +cowboy_req:read_part - Read the next multipart headers + +== Description + +[source,erlang] +---- +read_part(Req :: cowboy_req:req()) + -> read_part(Req, #{}) + +read_part(Req :: cowboy_req:req(), Opts) + -> {ok, Headers, Req} | {done, Req} + +Opts :: cowboy_req:read_body_opts() +Headers :: cow_multipart:headers() +---- + +Read the next part of a multipart body. + +This function reads the request body and parses it as +multipart. Each parts of a multipart representation have +their own headers and body. This function parses and returns +headers. Examples of multipart media types are +`multipart/form-data` and `multipart/byteranges`. + +Cowboy will skip any data remaining until the beginning of +the next part. This includes the preamble to the multipart +message but also the body of a previous part if it hasn't +been read. Both are skipped automatically when calling this +function. + +Cowboy will read the body before parsing in chunks of size +up to 64KB, with a period of 5 seconds. This is tailored for +reading part headers and might not be the most efficient for +skipping the previous part's body. + +The headers returned are MIME headers, *NOT* HTTP headers. +They can be parsed using the functions from the `cow_multipart` +module. In addition, the `cow_multipart:form_data/1` function +can be used to quickly extract information from `multipart/form-data` +representations. + +// @todo Proper link to cow_multipart:form_data. + +Once a part has been read, it can not be read again. + +Once the body has been read, Cowboy sets the content-length +header if it was not previously provided. + +// @todo Limit the maximum size of multipart headers. + +== Arguments + +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 containing the next part's headers +as a list of key/values. + +A `done` tuple is returned if there are no more parts to read. + +The Req object returned in the tuple must be used for 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.0*: Function introduced. Replaces `part/1,2`. + +== Examples + +.Read all parts +[source,erlang] +---- +acc_multipart(Req0, Acc) -> + case cowboy_req:read_part(Req0) of + {ok, Headers, Req1} -> + {ok, Body, Req} = stream_body(Req1, <<>>), + acc_multipart(Req, [{Headers, Body}|Acc]); + {done, Req} -> + {lists:reverse(Acc), Req} + end. + +stream_body(Req0, Acc) -> + case cowboy_req:read_part_body(Req0) of + {more, Data, Req} -> + stream_body(Req, << Acc/binary, Data/binary >>); + {ok, Data, Req} -> + {ok, << Acc/binary, Data/binary >>, Req} + end. +---- + +.Read all part headers, skipping bodies +[source,erlang] +---- +skip_body_multipart(Req0, Acc) -> + case cowboy_req:read_part(Req0) of + {ok, Headers, Req} -> + skip_body_multipart(Req, [Headers|Acc]); + {done, Req} -> + {lists:reverse(Acc), Req} + end. +---- + +.Read a part header in larger chunks +[source,erlang] +---- +{ok, Headers, Req} = cowboy_req:read_part(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_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 new file mode 100644 index 0000000..36b21ec --- /dev/null +++ b/doc/src/manual/cowboy_req.read_part_body.asciidoc @@ -0,0 +1,100 @@ += cowboy_req:read_part_body(3) + +== Name + +cowboy_req:read_part_body - Read the current part's body + +== Description + +[source,erlang] +---- +read_part_body(Req :: cowboy_req:req()) + -> read_part_body(Req, #{}) + +read_part_body(Req :: cowboy_req:req(), Opts) + -> {ok, Data :: binary(), Req} + | {more, Data :: binary(), Req} + +Opts :: cowboy_req:read_body_opts() +---- + +Read the body of the current part of the multipart message. + +This function reads the request body and parses it as +multipart. Each parts of a multipart representation have +their own headers and body. This function returns the +body of the current part. Examples of multipart media types +are `multipart/form-data` and `multipart/byteranges`. + +This function reads a chunk of the part's body. A `more` tuple +is returned when more data remains to be read. Call the function +repeatedly until an `ok` tuple is returned to read the entire body. + +Once a part has been read, it can not be read again. + +Once the body has been read, Cowboy sets the content-length +header if it was not previously provided. + +// @todo Limit the maximum size of multipart headers. + +== Arguments + +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 uses the same default options as the +link:man:cowboy_req:read_body(3)[cowboy_req:read_body(3)] +function. + +== Return value + +A `more` tuple is returned when there are more data to be read. + +An `ok` tuple is returned when there are no more data to be read. + +The data is always returned as a binary. + +The Req object returned in the tuple must be used for 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.0*: Function introduced. Replaces `part_body/1,2`. + +== Examples + +.Read a full part's body +[source,erlang] +---- +stream_body(Req0, Acc) -> + case cowboy_req:read_part_body(Req0) of + {more, Data, Req} -> + stream_body(Req, << Acc/binary, Data/binary >>); + {ok, Data, Req} -> + {ok, << Acc/binary, Data/binary >>, Req} + end. +---- + +.Ensure a part's body is smaller than 64KB +[source,erlang] +---- +{ok, Body, Req} = cowboy_req:read_part_body(Req0, #{length => 64000}). +---- + +== 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)] diff --git a/doc/src/manual/cowboy_req.read_urlencoded_body.asciidoc b/doc/src/manual/cowboy_req.read_urlencoded_body.asciidoc new file mode 100644 index 0000000..f8a72ab --- /dev/null +++ b/doc/src/manual/cowboy_req.read_urlencoded_body.asciidoc @@ -0,0 +1,94 @@ += cowboy_req:read_urlencoded_body(3) + +== Name + +cowboy_req:read_urlencoded_body - Read and parse a urlencoded request body + +== Description + +[source,erlang] +---- +read_urlencoded_body(Req :: cowboy_req:req()) + -> read_urlencoded_body(Req, #{}) + +read_urlencoded_body(Req :: cowboy_req:req(), Opts) + -> {ok, Body, Req} + +Opts :: cowboy_req:read_body_opts() +Body :: [{Key :: binary(), Value :: binary() | true}] +---- + +Read and parse a urlencoded request body. + +This function reads the request body and parses it as +`application/x-www-form-urlencoded`. It returns a list +of key/values. + +The urlencoded media type is used by Web browsers when +submitting HTML forms using the POST method. + +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 + +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 containing a list of key/values found +in the body. + +The Req object returned in the tuple must be used for 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.0*: Function introduced. Replaces `body_qs/1,2`. + +== Examples + +.Read a urlencoded body +[source,erlang] +---- +{ok, Body, Req} = cowboy_req:read_urlencoded_body(Req0), +{_, Lang} = lists:keyfind(<<"lang">>, 1, Body). +---- + +.Allow large urlencoded bodies +[source,erlang] +---- +{ok, Body, Req} = cowboy_req:read_urlencoded_body(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_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