From b09f3a570d702be7a55c36e5f5b4b63b26198637 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Thu, 23 Jan 2014 15:54:20 +0100 Subject: Clarify what stream_body is doing --- manual/cowboy_req.md | 17 +++++++++++------ 1 file 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. -- cgit v1.2.3