aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2014-01-23 15:54:20 +0100
committerLoïc Hoguin <[email protected]>2014-01-23 15:54:20 +0100
commitb09f3a570d702be7a55c36e5f5b4b63b26198637 (patch)
tree14103cd4ba036f5a0cf2a025d0b373b595f64350
parent0ec713fc4b185c3cd0f6b2e7ec2c5f198361bddd (diff)
downloadcowboy-b09f3a570d702be7a55c36e5f5b4b63b26198637.tar.gz
cowboy-b09f3a570d702be7a55c36e5f5b4b63b26198637.tar.bz2
cowboy-b09f3a570d702be7a55c36e5f5b4b63b26198637.zip
Clarify what stream_body is doing
-rw-r--r--manual/cowboy_req.md17
1 files changed, 11 insertions, 6 deletions
diff --git a/manual/cowboy_req.md b/manual/cowboy_req.md
index d7af41f..1d3841d 100644
--- a/manual/cowboy_req.md
+++ b/manual/cowboy_req.md
@@ -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.