Add the man pages for body reading functions

[ci skip]

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(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 in a multipart body
+* link:man:cowboy_req:read_part_body(3)[cowboy_req:read_part_body(3)] - Read the current part's body
 
 Response:
 

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)]

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)]

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)]

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)]

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)]

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)]