summaryrefslogtreecommitdiffstats
path: root/docs/en/cowboy/2.0/guide/req_body/index.html
diff options
context:
space:
mode:
Diffstat (limited to 'docs/en/cowboy/2.0/guide/req_body/index.html')
-rw-r--r--docs/en/cowboy/2.0/guide/req_body/index.html281
1 files changed, 142 insertions, 139 deletions
diff --git a/docs/en/cowboy/2.0/guide/req_body/index.html b/docs/en/cowboy/2.0/guide/req_body/index.html
index 821b512c..4fce0fd5 100644
--- a/docs/en/cowboy/2.0/guide/req_body/index.html
+++ b/docs/en/cowboy/2.0/guide/req_body/index.html
@@ -7,7 +7,7 @@
<meta name="description" content="">
<meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara">
- <meta name="generator" content="Hugo 0.17" />
+ <meta name="generator" content="Hugo 0.26" />
<title>Nine Nines: Reading the request body</title>
@@ -67,150 +67,153 @@
<h1 class="lined-header"><span>Reading the request body</span></h1>
-<div class="paragraph"><p>The request body can be read using the Req object.</p></div>
-<div class="paragraph"><p>Cowboy will not attempt to read the body until requested.
-You need to call the body reading functions in order to
-retrieve it.</p></div>
-<div class="paragraph"><p>Cowboy will not cache the body, it is therefore only
-possible to read it once.</p></div>
-<div class="paragraph"><p>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.</p></div>
-<div class="paragraph"><p>Cowboy provides functions for reading the body raw,
-and read and parse form urlencoded or <a href="../multipart">multipart bodies</a>.
-The latter is covered in its own chapter.</p></div>
-<div class="sect1">
-<h2 id="_request_body_presence">Request body presence</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Not all requests come with a body. You can check for
-the presence of a request body with this function:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_body</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>It returns <code>true</code> if there is a body; <code>false</code> otherwise.</p></div>
-<div class="paragraph"><p>In practice, this function is rarely used. When the
-method is <code>POST</code>, <code>PUT</code> or <code>PATCH</code>, the request body
-is often required by the application, which should
-just attempt to read it directly.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_request_body_length">Request body length</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can obtain the length of the body:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Length</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:body_length</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Note that the length may not be known in advance. In
-that case <code>undefined</code> will be returned. This can happen
-with HTTP/1.1&#8217;s chunked transfer-encoding, or HTTP/2
-when no content-length was provided.</p></div>
-<div class="paragraph"><p>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.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_reading_the_body">Reading the body</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can read the entire body with one function call:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Cowboy returns an <code>ok</code> tuple when the body has been
-read fully.</p></div>
-<div class="paragraph"><p>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.</p></div>
-<div class="paragraph"><p>These values can be customized. For example, to read
-only up to 1MB for up to 5 seconds:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>,
- #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=&gt;</span> <span style="color: #993399">1000000</span>, <span style="color: #0000FF">period</span> <span style="color: #990000">=&gt;</span> <span style="color: #993399">5000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You may also disable the length limit:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=&gt;</span> <span style="color: #FF6600">infinity</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>This makes the function wait 15 seconds and return with
-whatever arrived during that period. This is not
-recommended for public facing applications.</p></div>
-<div class="paragraph"><p>These two options can effectively be used to control
-the rate of transmission of the request body.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_streaming_the_body">Streaming the body</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>When the body is too large, the first call will return
-a <code>more</code> tuple instead of <code>ok</code>. You can call the
-function again to read more of the body, reading
-it one chunk at a time.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">read_body_to_console</span></span>(<span style="color: #009900">Req0</span>) <span style="color: #990000">-&gt;</span>
- <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-&gt;</span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s"</span>, [<span style="color: #009900">Data</span>]),
- <span style="color: #009900">Req</span>;
- {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-&gt;</span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s"</span>, [<span style="color: #009900">Data</span>]),
- <span style="font-weight: bold"><span style="color: #000000">read_body_to_console</span></span>(<span style="color: #009900">Req</span>)
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The <code>length</code> and <code>period</code> options can also be used.
-They need to be passed for every call.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_reading_a_form_urlencoded_body">Reading a form urlencoded body</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy provides a convenient function for reading and
-parsing bodies sent as application/x-www-form-urlencoded.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">KeyValues</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_urlencoded_body</span></span>(<span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>This function returns a list of key/values, exactly like
-the function <code>cowboy_req:parse_qs/1</code>.</p></div>
-<div class="paragraph"><p>The defaults for this function are different. Cowboy will
-read for up to 64KB and up to 5 seconds. They can be modified:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">KeyValues</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_urlencoded_body</span></span>(<span style="color: #009900">Req0</span>,
- #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=&gt;</span> <span style="color: #993399">4096</span>, <span style="color: #0000FF">period</span> <span style="color: #990000">=&gt;</span> <span style="color: #993399">3000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
+<div class="paragraph"><p>The request body can be read using the Req object.</p></div>
+<div class="paragraph"><p>Cowboy will not attempt to read the body until requested.
+You need to call the body reading functions in order to
+retrieve it.</p></div>
+<div class="paragraph"><p>Cowboy will not cache the body, it is therefore only
+possible to read it once.</p></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>Cowboy provides functions for reading the body raw,
+and read and parse form urlencoded or <a href="../multipart">multipart bodies</a>.
+The latter is covered in its own chapter.</p></div>
+<div class="sect1">
+<h2 id="_request_body_presence">Request body presence</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Not all requests come with a body. You can check for
+the presence of a request body with this function:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_body</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>It returns <code>true</code> if there is a body; <code>false</code> otherwise.</p></div>
+<div class="paragraph"><p>In practice, this function is rarely used. When the
+method is <code>POST</code>, <code>PUT</code> or <code>PATCH</code>, the request body
+is often required by the application, which should
+just attempt to read it directly.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_request_body_length">Request body length</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>You can obtain the length of the body:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">Length</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:body_length</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Note that the length may not be known in advance. In
+that case <code>undefined</code> will be returned. This can happen
+with HTTP/1.1&#8217;s chunked transfer-encoding, or HTTP/2
+when no content-length was provided.</p></div>
+<div class="paragraph"><p>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.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_reading_the_body">Reading the body</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>You can read the entire body with one function call:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Cowboy returns an <code>ok</code> tuple when the body has been
+read fully.</p></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>These values can be customized. For example, to read
+only up to 1MB for up to 5 seconds:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>,
+ #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=&gt;</span> <span style="color: #993399">1000000</span>, <span style="color: #0000FF">period</span> <span style="color: #990000">=&gt;</span> <span style="color: #993399">5000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>You may also disable the length limit:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=&gt;</span> <span style="color: #FF6600">infinity</span>})<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>This makes the function wait 15 seconds and return with
+whatever arrived during that period. This is not
+recommended for public facing applications.</p></div>
+<div class="paragraph"><p>These two options can effectively be used to control
+the rate of transmission of the request body.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_streaming_the_body">Streaming the body</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>When the body is too large, the first call will return
+a <code>more</code> tuple instead of <code>ok</code>. You can call the
+function again to read more of the body, reading
+it one chunk at a time.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">read_body_to_console</span></span>(<span style="color: #009900">Req0</span>) <span style="color: #990000">-&gt;</span>
+ <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
+ {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-&gt;</span>
+ <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s"</span>, [<span style="color: #009900">Data</span>]),
+ <span style="color: #009900">Req</span>;
+ {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-&gt;</span>
+ <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s"</span>, [<span style="color: #009900">Data</span>]),
+ <span style="font-weight: bold"><span style="color: #000000">read_body_to_console</span></span>(<span style="color: #009900">Req</span>)
+ <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>The <code>length</code> and <code>period</code> options can also be used.
+They need to be passed for every call.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_reading_a_form_urlencoded_body">Reading a form urlencoded body</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Cowboy provides a convenient function for reading and
+parsing bodies sent as application/x-www-form-urlencoded.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">KeyValues</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_urlencoded_body</span></span>(<span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>This function returns a list of key/values, exactly like
+the function <code>cowboy_req:parse_qs/1</code>.</p></div>
+<div class="paragraph"><p>The defaults for this function are different. Cowboy will
+read for up to 64KB and up to 5 seconds. They can be modified:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">KeyValues</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_urlencoded_body</span></span>(<span style="color: #009900">Req0</span>,
+ #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=&gt;</span> <span style="color: #993399">4096</span>, <span style="color: #0000FF">period</span> <span style="color: #990000">=&gt;</span> <span style="color: #993399">3000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
+</div>
+</div>
+
+
+
<nav style="margin:1em 0">
generated by cgit v1.2.3 (git 2.25.1) at 2024-07-01 07:05:41 +0000