From 1b863c350ba1f9b8ad1cb458df514ab0fe6bb127 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Mon, 11 Dec 2017 11:27:17 +0100
Subject: Add documentation for Cowboy 2.2

---
 docs/en/cowboy/2.2/guide/req_body.asciidoc | 130 +++++++++++++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 docs/en/cowboy/2.2/guide/req_body.asciidoc

(limited to 'docs/en/cowboy/2.2/guide/req_body.asciidoc')

diff --git a/docs/en/cowboy/2.2/guide/req_body.asciidoc b/docs/en/cowboy/2.2/guide/req_body.asciidoc
new file mode 100644
index 00000000..4906811e
--- /dev/null
+++ b/docs/en/cowboy/2.2/guide/req_body.asciidoc
@@ -0,0 +1,130 @@
+[[req_body]]
+== Reading the request body
+
+The request body can be read using the Req object.
+
+Cowboy will not attempt to read the body until requested.
+You need to call the body reading functions in order to
+retrieve it.
+
+Cowboy will not cache the body, it is therefore only
+possible to read it once.
+
+You are not required to read it, however. If a body is
+present and was not read, Cowboy will either cancel or
+skip its download, depending on the protocol.
+
+Cowboy provides functions for reading the body raw,
+and read and parse form urlencoded or xref:multipart[multipart bodies].
+The latter is covered in its own chapter.
+
+=== Request body presence
+
+Not all requests come with a body. You can check for
+the presence of a request body with this function:
+
+[source,erlang]
+cowboy_req:has_body(Req).
+
+It returns `true` if there is a body; `false` otherwise.
+
+In practice, this function is rarely used. When the
+method is `POST`, `PUT` or `PATCH`, the request body
+is often required by the application, which should
+just attempt to read it directly.
+
+=== Request body length
+
+You can obtain the length of the body:
+
+[source,erlang]
+Length = cowboy_req:body_length(Req).
+
+Note that the length may not be known in advance. In
+that case `undefined` will be returned. This can happen
+with HTTP/1.1's chunked transfer-encoding, or HTTP/2
+when no content-length was provided.
+
+Cowboy will update the body length in the Req object
+once the body has been read completely. A length will
+always be returned when attempting to call this function
+after reading the body completely.
+
+=== Reading the body
+
+You can read the entire body with one function call:
+
+[source,erlang]
+{ok, Data, Req} = cowboy_req:read_body(Req0).
+
+Cowboy returns an `ok` tuple when the body has been
+read fully.
+
+By default, Cowboy will attempt to read up to 8MB
+of data, for up to 15 seconds. The call will return
+once Cowboy has read at least 8MB of data, or at
+the end of the 15 seconds period.
+
+These values can be customized. For example, to read
+only up to 1MB for up to 5 seconds:
+
+[source,erlang]
+----
+{ok, Data, Req} = cowboy_req:read_body(Req0,
+    #{length => 1000000, period => 5000}).
+----
+
+You may also disable the length limit:
+
+[source,erlang]
+{ok, Data, Req} = cowboy_req:read_body(Req0, #{length => infinity}).
+
+This makes the function wait 15 seconds and return with
+whatever arrived during that period. This is not
+recommended for public facing applications.
+
+These two options can effectively be used to control
+the rate of transmission of the request body.
+
+=== Streaming the body
+
+When the body is too large, the first call will return
+a `more` tuple instead of `ok`. You can call the
+function again to read more of the body, reading
+it one chunk at a time.
+
+[source,erlang]
+----
+read_body_to_console(Req0) ->
+    case cowboy_req:read_body(Req0) of
+        {ok, Data, Req} ->
+            io:format("~s", [Data]),
+            Req;
+        {more, Data, Req} ->
+            io:format("~s", [Data]),
+            read_body_to_console(Req)
+    end.
+----
+
+The `length` and `period` options can also be used.
+They need to be passed for every call.
+
+=== Reading a form urlencoded body
+
+Cowboy provides a convenient function for reading and
+parsing bodies sent as application/x-www-form-urlencoded.
+
+[source,erlang]
+{ok, KeyValues, Req} = cowboy_req:read_urlencoded_body(Req0).
+
+This function returns a list of key/values, exactly like
+the function `cowboy_req:parse_qs/1`.
+
+The defaults for this function are different. Cowboy will
+read for up to 64KB and up to 5 seconds. They can be modified:
+
+[source,erlang]
+----
+{ok, KeyValues, Req} = cowboy_req:read_urlencoded_body(Req0,
+    #{length => 4096, period => 3000}).
+----
-- 
cgit v1.2.3