umgeher/cowboy
0
Fork 0
mirror of https://github.com/ninenines/cowboy.git synced 2025-07-15 20:50:24 +00:00
Code Issues Wiki Activity

Clarify what stream_body is doing

Browse source
This commit is contained in:
Loïc Hoguin 2014-01-23 15:54:20 +01:00
parent 0ec713fc4b
commit b09f3a570d
1 changed files with 11 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

17
manual/cowboy_req.md
View file

@ -419,26 +419,31 @@ Request body related exports
> read before.
### stream_body(Req) -> stream_body(1000000, Req)
### stream_body(MaxSegmentSize, Req) -> {ok, Data, Req2}
### stream_body(MaxReadSize, Req) -> {ok, Data, Req2}
| {done, Req2} | {error, Reason}
> Types:
> * MaxSegmentSize = non_neg_integer()
> * MaxReadSize = non_neg_integer()
> * Data = binary()
> * Reason = atom()
>
> Stream the request body.
>
> This function will return a segment of the request body
> with a size of up to `MaxSegmentSize`, or 1MB by default.
> This function can be called repeatedly until a `done` tuple
> is returned, indicating the body has been fully received.
> This function will return the next segment of the body.
>
> Cowboy will properly handle chunked transfer-encoding by
> default. If any other transfer-encoding or content-encoding
> has been used for the request, custom decoding functions
> can be used. They must be specified using `init_stream/4`.
>
> The amount of data returned by this function may vary
> depending on the current state of the request. If data
> is already available in the buffer then it is used fully,
> otherwise Cowboy will read up to `MaxReadSize` bytes from
> the socket. By default Cowboy will read up to 1MB of data.
> It is then decoded, which may grow or shrink it, depending
> on the encoding headers, before it is finally returned.
>
> After the body has been streamed fully, Cowboy will remove
> the transfer-encoding header from the `Req` object, and add
> the content-length header if it wasn't already there.