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 | 188 |
1 files changed, 94 insertions, 94 deletions
diff --git a/docs/en/cowboy/2.0/guide/multipart/index.html b/docs/en/cowboy/2.0/guide/multipart/index.html index dba83e90..5f661d44 100644 --- a/docs/en/cowboy/2.0/guide/multipart/index.html +++ b/docs/en/cowboy/2.0/guide/multipart/index.html @@ -70,33 +70,18 @@ <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. Multipart messages are a
-container for parts of any content-type.</p></div>
-<div class="paragraph"><p>For example, a multipart message may have a part
-containing text and a second part containing an
-image. This is what allows you to attach files
-to emails.</p></div>
+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> content-type. This is
-the content-type you have to use when you want browsers
-to be allowed to upload files through HTML forms.</p></div>
-<div class="paragraph"><p>Multipart is of course not required for uploading
-files, it is only required when you want to do so
-through HTML forms.</p></div>
-<div class="paragraph"><p>You can read and parse multipart messages using the
-Req object directly.</p></div>
-<div class="paragraph"><p>Cowboy defines two functions that allows you to get
-information about each part and read their contents.</p></div>
-<div class="sect1">
-<h2 id="_structure">Structure</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A multipart message is a list of parts. Parts may
-contain either a multipart message or a non-multipart
-content-type. This allows parts to be arranged in a
-tree structure, although this is a rare case as far
-as the Web is concerned.</p></div>
-</div>
-</div>
+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">
<h2 id="_form_data">Form-data</h2>
<div class="sectionbody">
@@ -106,28 +91,24 @@ 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 use one part of the
-message for each form field. This means that a file
-input field will be sent in its own part, but the
-same applies to all other kinds of fields.</p></div>
+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 content-type
+<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">
-<h2 id="_checking_the_content_type">Checking the content-type</h2>
+<h2 id="_checking_for_multipart_messages">Checking for multipart messages</h2>
<div class="sectionbody">
-<div class="paragraph"><p>While there is a variety of multipart messages, the
-most common on the Web is <code>multipart/form-data</code>. It’s
-the type of message being sent when an HTML form
-allows uploading files.</p></div>
-<div class="paragraph"><p>You can quickly figure out if a multipart message
-has been sent by parsing the <code>content-type</code> header.</p></div>
+<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 3.1.8
by Lorenzo Bettini
@@ -140,72 +121,92 @@ http://www.gnu.org/software/src-highlite --> <div class="sect1">
<h2 id="_reading_a_multipart_message">Reading a multipart message</h2>
<div class="sectionbody">
-<div class="paragraph"><p>To read a message you have to iterate over all its
-parts. Then, for each part, you can inspect its headers
-and read its body.</p></div>
+<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 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">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">cowboy_req:part</span></span>(<span style="color: #009900">Req</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">Req2</span>} <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">_Body</span>, <span style="color: #009900">Req3</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:part_body</span></span>(<span style="color: #009900">Req2</span>),
- <span style="font-weight: bold"><span style="color: #000000">multipart</span></span>(<span style="color: #009900">Req3</span>);
- {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req2</span>} <span style="color: #990000">-></span>
- <span style="color: #009900">Req2</span>
+<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>Parts do not have a size limit. When a part body is
-too big, Cowboy will return what it read so far and
-allow you to continue if you wish to do so.</p></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. This function will
-tell you if the part is for a normal field or if it
-is a file being uploaded.</p></div>
-<div class="paragraph"><p>This can be used for example to allow large part bodies
-for files but crash when a normal field is too large.</p></div>
+<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 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">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">cowboy_req:part</span></span>(<span style="color: #009900">Req</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">Req2</span>} <span style="color: #990000">-></span>
- <span style="color: #009900">Req4</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>
+<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">Req3</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:part_body</span></span>(<span style="color: #009900">Req2</span>),
- <span style="color: #009900">Req3</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: #009900">_CTransferEncoding</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">stream_file</span></span>(<span style="color: #009900">Req2</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">Req4</span>);
- {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req2</span>} <span style="color: #990000">-></span>
- <span style="color: #009900">Req2</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">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">cowboy_req:part_body</span></span>(<span style="color: #009900">Req</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></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="color: #009900">Req2</span>;
- {<span style="color: #FF6600">more</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">stream_file</span></span>(<span style="color: #009900">Req2</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">_Body</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">_Body</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>By default the body chunk Cowboy will return is limited
-to 8MB. This can of course be overriden. Both functions
-can take a second argument, the same list of options that
-will be passed to <code>cowboy_req:body/2</code> function.</p></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 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 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">
<h2 id="_skipping_unwanted_parts">Skipping unwanted parts</h2>
<div class="sectionbody">
-<div class="paragraph"><p>If you do not want to read a part’s body, you can skip it.
-Skipping is easy. If you do not call the function to read
-the part’s body, Cowboy will automatically skip it when
-you request the next part.</p></div>
+<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">
@@ -213,23 +214,22 @@ all bodies:</p></div> 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">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">cowboy_req:part</span></span>(<span style="color: #009900">Req</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">Req2</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">multipart</span></span>(<span style="color: #009900">Req2</span>);
- {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req2</span>} <span style="color: #990000">-></span>
- <span style="color: #009900">Req2</span>
+<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: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,
+being too big, you can simply continue with the next part.
Cowboy will automatically skip what remains.</p></div>
-<div class="paragraph"><p>Note that the skipping rate may not be adequate for your
-application. If you observe poor performance when skipping,
-you might want to consider manually skipping by calling
-the <code>cowboy_req:part_body/1</code> function directly.</p></div>
-<div class="paragraph"><p>And if you started reading the message but decide that you
-do not need the remaining parts, you can simply stop reading
-entirely and Cowboy will automatically figure out what to do.</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>
|