cowboy/doc/src/manual/cowboy_req.read_part.asciidoc

= 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 :: #{binary() => binary()}
----

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 map.

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