diff options
Diffstat (limited to 'docs/en/cowboy/2.0/guide/multipart/index.html')
| -rw-r--r-- | docs/en/cowboy/2.0/guide/multipart/index.html | 220 |
1 files changed, 79 insertions, 141 deletions
diff --git a/docs/en/cowboy/2.0/guide/multipart/index.html b/docs/en/cowboy/2.0/guide/multipart/index.html index 73525df2..7157eab1 100644 --- a/docs/en/cowboy/2.0/guide/multipart/index.html +++ b/docs/en/cowboy/2.0/guide/multipart/index.html @@ -62,169 +62,107 @@ <h1 class="lined-header"><span>Multipart requests</span></h1> -<div class="paragraph"><p>Multipart originates from MIME, an Internet standard that -extends the format of emails.</p></div> -<div class="paragraph"><p>A multipart message is a list of parts. A part contains -headers and a body. The body of the parts may be -of any media type, and contain text or binary data. -It is possible for parts to contain a multipart media -type.</p></div> -<div class="paragraph"><p>In the context of HTTP, multipart is most often used -with the <code>multipart/form-data</code> media type. It is what -browsers use to upload files through HTML forms.</p></div> -<div class="paragraph"><p>The <code>multipart/byteranges</code> is also common. It is the -media type used to send arbitrary bytes from a resource, -enabling clients to resume downloads.</p></div> -<div class="sect1"> +<p>Multipart originates from MIME, an Internet standard that extends the format of emails.</p> +<p>A multipart message is a list of parts. A part contains headers and a body. The body of the parts may be of any media type, and contain text or binary data. It is possible for parts to contain a multipart media type.</p> +<p>In the context of HTTP, multipart is most often used with the <code>multipart/form-data</code> media type. It is what browsers use to upload files through HTML forms.</p> +<p>The <code>multipart/byteranges</code> is also common. It is the media type used to send arbitrary bytes from a resource, enabling clients to resume downloads.</p> <h2 id="_form_data">Form-data</h2> -<div class="sectionbody"> -<div class="paragraph"><p>In the normal case, when a form is submitted, the -browser will use the <code>application/x-www-form-urlencoded</code> -content-type. This type is just a list of keys and -values and is therefore not fit for uploading files.</p></div> -<div class="paragraph"><p>That’s where the <code>multipart/form-data</code> content-type -comes in. When the form is configured to use this -content-type, the browser will create a multipart -message where each part corresponds to a field on -the form. For files, it also adds some metadata in -the part headers, like the file name.</p></div> -<div class="paragraph"><p>A form with a text input, a file input and a select -choice box will result in a multipart message with -three parts, one for each field.</p></div> -<div class="paragraph"><p>The browser does its best to determine the media type -of the files it sends this way, but you should not -rely on it for determining the contents of the file. -Proper investigation of the contents is recommended.</p></div> -</div> -</div> -<div class="sect1"> +<p>In the normal case, when a form is submitted, the browser will use the <code>application/x-www-form-urlencoded</code> content-type. This type is just a list of keys and values and is therefore not fit for uploading files.</p> +<p>That's where the <code>multipart/form-data</code> content-type comes in. When the form is configured to use this content-type, the browser will create a multipart message where each part corresponds to a field on the form. For files, it also adds some metadata in the part headers, like the file name.</p> +<p>A form with a text input, a file input and a select choice box will result in a multipart message with three parts, one for each field.</p> +<p>The browser does its best to determine the media type of the files it sends this way, but you should not rely on it for determining the contents of the file. Proper investigation of the contents is recommended.</p> <h2 id="_checking_for_multipart_messages">Checking for multipart messages</h2> -<div class="sectionbody"> -<div class="paragraph"><p>The content-type header indicates the presence of -a multipart message:</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<p>The content-type header indicates the presence of a multipart message:</p> +<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: #990000"><<</span><span style="color: #FF0000">"multipart"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"form-data"</span><span style="color: #990000">>></span>, <span style="color: #990000">_</span>} - <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> -</div> -</div> -<div class="sect1"> +<pre><tt>{<font color="#990000"><<</font><font color="#FF0000">"multipart"</font><font color="#990000">>></font>, <font color="#990000"><<</font><font color="#FF0000">"form-data"</font><font color="#990000">>></font>, <font color="#990000">_</font>} + <font color="#990000">=</font> <b><font color="#000000">cowboy_req:parse_header</font></b>(<font color="#990000"><<</font><font color="#FF0000">"content-type"</font><font color="#990000">>></font>, <font color="#009900">Req</font>)<font color="#990000">.</font></tt></pre> +</div></div> <h2 id="_reading_a_multipart_message">Reading a multipart message</h2> -<div class="sectionbody"> -<div class="paragraph"><p>Cowboy provides two sets of functions for reading -request bodies as multipart messages.</p></div> -<div class="paragraph"><p>The <code>cowboy_req:read_part/1,2</code> functions return the -next part’s headers, if any.</p></div> -<div class="paragraph"><p>The <code>cowboy_req:read_part_body/1,2</code> functions return -the current part’s body. For large bodies you may -need to call the function multiple times.</p></div> -<div class="paragraph"><p>To read a multipart message you need to iterate over -all its parts:</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<p>Cowboy provides two sets of functions for reading request bodies as multipart messages.</p> +<p>The <code>cowboy_req:read_part/1,2</code> functions return the next part's headers, if any.</p> +<p>The <code>cowboy_req:read_part_body/1,2</code> functions return the current part's body. For large bodies you may need to call the function multiple times.</p> +<p>To read a multipart message you need to iterate over all its parts:</p> +<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">multipart</span></span>(<span style="color: #009900">Req0</span>) <span style="color: #990000">-></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_part</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">_Headers</span>, <span style="color: #009900">Req1</span>} <span style="color: #990000">-></span> - {<span style="color: #FF6600">ok</span>, <span style="color: #009900">_Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part_body</span></span>(<span style="color: #009900">Req1</span>), - <span style="font-weight: bold"><span style="color: #000000">multipart</span></span>(<span style="color: #009900">Req</span>); - {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></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>When part bodies are too large, Cowboy will return -a <code>more</code> tuple, and allow you to loop until the part -body has been fully read.</p></div> -<div class="paragraph"><p>The function <code>cow_multipart:form_data/1</code> can be used -to quickly obtain information about a part from a -<code>multipart/form-data</code> message. The function returns -a <code>data</code> or a <code>file</code> tuple depending on whether this -is a normal field or a file being uploaded.</p></div> -<div class="paragraph"><p>The following snippet will use this function and -use different strategies depending on whether the -part is a file:</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<pre><tt><b><font color="#000000">multipart</font></b>(<font color="#009900">Req0</font>) <font color="#990000">-></font> + <b><font color="#0000FF">case</font></b> <b><font color="#000000">cowboy_req:read_part</font></b>(<font color="#009900">Req0</font>) <b><font color="#0000FF">of</font></b> + {<font color="#FF6600">ok</font>, <font color="#009900">_Headers</font>, <font color="#009900">Req1</font>} <font color="#990000">-></font> + {<font color="#FF6600">ok</font>, <font color="#009900">_Body</font>, <font color="#009900">Req</font>} <font color="#990000">=</font> <b><font color="#000000">cowboy_req:read_part_body</font></b>(<font color="#009900">Req1</font>), + <b><font color="#000000">multipart</font></b>(<font color="#009900">Req</font>); + {<font color="#FF6600">done</font>, <font color="#009900">Req</font>} <font color="#990000">-></font> + <font color="#009900">Req</font> + <b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> +<p>When part bodies are too large, Cowboy will return a <code>more</code> tuple, and allow you to loop until the part body has been fully read.</p> +<p>The function <code>cow_multipart:form_data/1</code> can be used to quickly obtain information about a part from a <code>multipart/form-data</code> message. The function returns a <code>data</code> or a <code>file</code> tuple depending on whether this is a normal field or a file being uploaded.</p> +<p>The following snippet will use this function and use different strategies depending on whether the part is a file:</p> +<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">multipart</span></span>(<span style="color: #009900">Req0</span>) <span style="color: #990000">-></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_part</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">Headers</span>, <span style="color: #009900">Req1</span>} <span style="color: #990000">-></span> - <span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">cow_multipart:form_data</span></span>(<span style="color: #009900">Headers</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> - {<span style="color: #FF6600">data</span>, <span style="color: #009900">_FieldName</span>} <span style="color: #990000">-></span> - {<span style="color: #FF6600">ok</span>, <span style="color: #009900">_Body</span>, <span style="color: #009900">Req2</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part_body</span></span>(<span style="color: #009900">Req1</span>), - <span style="color: #009900">Req2</span>; - {<span style="color: #FF6600">file</span>, <span style="color: #009900">_FieldName</span>, <span style="color: #009900">_Filename</span>, <span style="color: #009900">_CType</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">stream_file</span></span>(<span style="color: #009900">Req1</span>) - <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>, - <span style="font-weight: bold"><span style="color: #000000">multipart</span></span>(<span style="color: #009900">Req</span>); - {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> - <span style="color: #009900">Req</span> - <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span> - -<span style="font-weight: bold"><span style="color: #000000">stream_file</span></span>(<span style="color: #009900">Req0</span>) <span style="color: #990000">-></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_part_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">_LastBodyChunk</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> - <span style="color: #009900">Req</span>; - {<span style="color: #FF6600">more</span>, <span style="color: #009900">_BodyChunk</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">stream_file</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>Both the part header and body reading functions can take -options that will be given to the request body reading -functions. By default, <code>cowboy_req:read_part/1</code> reads -up to 64KB for up to 5 seconds. <code>cowboy_req:read_part_body/1</code> -has the same defaults as <code>cowboy_req:read_body/1</code>.</p></div> -<div class="paragraph"><p>To change the defaults for part headers:</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<pre><tt><b><font color="#000000">multipart</font></b>(<font color="#009900">Req0</font>) <font color="#990000">-></font> + <b><font color="#0000FF">case</font></b> <b><font color="#000000">cowboy_req:read_part</font></b>(<font color="#009900">Req0</font>) <b><font color="#0000FF">of</font></b> + {<font color="#FF6600">ok</font>, <font color="#009900">Headers</font>, <font color="#009900">Req1</font>} <font color="#990000">-></font> + <font color="#009900">Req</font> <font color="#990000">=</font> <b><font color="#0000FF">case</font></b> <b><font color="#000000">cow_multipart:form_data</font></b>(<font color="#009900">Headers</font>) <b><font color="#0000FF">of</font></b> + {<font color="#FF6600">data</font>, <font color="#009900">_FieldName</font>} <font color="#990000">-></font> + {<font color="#FF6600">ok</font>, <font color="#009900">_Body</font>, <font color="#009900">Req2</font>} <font color="#990000">=</font> <b><font color="#000000">cowboy_req:read_part_body</font></b>(<font color="#009900">Req1</font>), + <font color="#009900">Req2</font>; + {<font color="#FF6600">file</font>, <font color="#009900">_FieldName</font>, <font color="#009900">_Filename</font>, <font color="#009900">_CType</font>} <font color="#990000">-></font> + <b><font color="#000000">stream_file</font></b>(<font color="#009900">Req1</font>) + <b><font color="#0000FF">end</font></b>, + <b><font color="#000000">multipart</font></b>(<font color="#009900">Req</font>); + {<font color="#FF6600">done</font>, <font color="#009900">Req</font>} <font color="#990000">-></font> + <font color="#009900">Req</font> + <b><font color="#0000FF">end</font></b><font color="#990000">.</font> + +<b><font color="#000000">stream_file</font></b>(<font color="#009900">Req0</font>) <font color="#990000">-></font> + <b><font color="#0000FF">case</font></b> <b><font color="#000000">cowboy_req:read_part_body</font></b>(<font color="#009900">Req0</font>) <b><font color="#0000FF">of</font></b> + {<font color="#FF6600">ok</font>, <font color="#009900">_LastBodyChunk</font>, <font color="#009900">Req</font>} <font color="#990000">-></font> + <font color="#009900">Req</font>; + {<font color="#FF6600">more</font>, <font color="#009900">_BodyChunk</font>, <font color="#009900">Req</font>} <font color="#990000">-></font> + <b><font color="#000000">stream_file</font></b>(<font color="#009900">Req</font>) + <b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> +<p>Both the part header and body reading functions can take options that will be given to the request body reading functions. By default, <code>cowboy_req:read_part/1</code> reads up to 64KB for up to 5 seconds. <code>cowboy_req:read_part_body/1</code> has the same defaults as <code>cowboy_req:read_body/1</code>.</p> +<p>To change the defaults for part headers:</p> +<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:read_part</span></span>(<span style="color: #009900">Req</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">128000</span>})<span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>And for part bodies:</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<pre><tt><b><font color="#000000">cowboy_req:read_part</font></b>(<font color="#009900">Req</font>, #{<b><font color="#000080">length</font></b> <font color="#990000">=></font> <font color="#993399">128000</font>})<font color="#990000">.</font></tt></pre> +</div></div> +<p>And for part bodies:</p> +<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:read_part_body</span></span>(<span style="color: #009900">Req</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">1000000</span>, <span style="color: #0000FF">period</span> <span style="color: #990000">=></span> <span style="color: #993399">7000</span>})<span style="color: #990000">.</span></tt></pre></div></div> -</div> -</div> -<div class="sect1"> +<pre><tt><b><font color="#000000">cowboy_req:read_part_body</font></b>(<font color="#009900">Req</font>, #{<b><font color="#000080">length</font></b> <font color="#990000">=></font> <font color="#993399">1000000</font>, <font color="#0000FF">period</font> <font color="#990000">=></font> <font color="#993399">7000</font>})<font color="#990000">.</font></tt></pre> +</div></div> <h2 id="_skipping_unwanted_parts">Skipping unwanted parts</h2> -<div class="sectionbody"> -<div class="paragraph"><p>Part bodies do not have to be read. Cowboy will automatically -skip it when you request the next part’s body.</p></div> -<div class="paragraph"><p>The following snippet reads all part headers and skips -all bodies:</p></div> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<p>Part bodies do not have to be read. Cowboy will automatically skip it when you request the next part's body.</p> +<p>The following snippet reads all part headers and skips all bodies:</p> +<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">multipart</span></span>(<span style="color: #009900">Req0</span>) <span style="color: #990000">-></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_part</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">_Headers</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">multipart</span></span>(<span style="color: #009900">Req</span>); - {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></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>Similarly, if you start reading the body and it ends up -being too big, you can simply continue with the next part. -Cowboy will automatically skip what remains.</p></div> -<div class="paragraph"><p>While Cowboy can skip part bodies automatically, the read -rate is not configurable. Depending on your application -you may want to skip manually, in particular if you observe -poor performance while skipping.</p></div> -<div class="paragraph"><p>You do not have to read all parts either. You can stop -reading as soon as you find the data you need.</p></div> -</div> -</div> +<pre><tt><b><font color="#000000">multipart</font></b>(<font color="#009900">Req0</font>) <font color="#990000">-></font> + <b><font color="#0000FF">case</font></b> <b><font color="#000000">cowboy_req:read_part</font></b>(<font color="#009900">Req0</font>) <b><font color="#0000FF">of</font></b> + {<font color="#FF6600">ok</font>, <font color="#009900">_Headers</font>, <font color="#009900">Req</font>} <font color="#990000">-></font> + <b><font color="#000000">multipart</font></b>(<font color="#009900">Req</font>); + {<font color="#FF6600">done</font>, <font color="#009900">Req</font>} <font color="#990000">-></font> + <font color="#009900">Req</font> + <b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> +<p>Similarly, if you start reading the body and it ends up being too big, you can simply continue with the next part. Cowboy will automatically skip what remains.</p> +<p>While Cowboy can skip part bodies automatically, the read rate is not configurable. Depending on your application you may want to skip manually, in particular if you observe poor performance while skipping.</p> +<p>You do not have to read all parts either. You can stop reading as soon as you find the data you need.</p> +<!-- @todo Cover the building of multipart messages.--> + |