Documentation for Multipart parser

Also added multipart.parse as a convenience function
15 years ago · eeaa267cbe
5 changed files with 444 additions and 6 deletions
--- a/doc/api.html
+++ b/doc/api.html
@ -1516,6 +1516,116 @@ After emitted no other events will be emitted on the response.</p></td>
 </p>
 </dd>
 </dl></div>
+<h3 id="_multipart_parsing">Multipart Parsing</h3><div style="clear:left"></div>
+<div class="paragraph"><p>A library to parse HTTP requests with <tt>multipart/form-data</tt> is included with
+Node.  To use it, <tt>require("/multipart.js")</tt>.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<tt>multipart.parse(options)</tt> 
+</dt>
+<dd>
+<div class="ulist"><ul>
+<li>
+<p>
+on success: Returns an object where each key holds the value of one part of
+                the stream. <tt>options</tt> can either be an instance of
+                <tt>http.ServerRequest</tt> or an object containing a <em>boundary</em> and a
+                <em>data</em> key.
+</p>
+</li>
+<li>
+<p>
+on error: no parameters.
+</p>
+</li>
+</ul></div>
+</dd>
+</dl></div>
+<h4 id="_tt_multipart_stream_tt"><tt>multipart.Stream</tt></h4>
+<div class="paragraph"><p>Here is an example for parsing a <tt>multipart/form-data</tt> request:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>var multipart = require('/multipart.js');
+var stream = new multipart.Stream(options);
+var parts = {};
+
+stream.addListener('part', function (part) {
+  var name = part.headers['Content-Disposition'].name;
+  var buffer = '';
+
+  part.addListener('body', function(chunk) {
+    buffer = buffer + chunk;
+  });
+
+  part.addListener('complete', function() {
+    parts[name] = buffer;
+  });
+});
+
+stream.addListener('complete', function() {
+  // The parts object now contains all parts and data
+});</tt></pre>
+</div></div>
+<div class="tableblock">
+<table rules="all"
+width="100%"
+frame="border"
+cellspacing="0" cellpadding="4">
+<col width="7%" />
+<col width="15%" />
+<col width="76%" />
+<thead>
+<tr>
+<th align="left" valign="top">Event           </th>
+<th align="left" valign="top"> Parameters   </th>
+<th align="left" valign="top"> Notes</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="left" valign="top"><p class="table"><tt>"part"</tt></p></td>
+<td align="left" valign="top"><p class="table"><tt>part</tt></p></td>
+<td align="left" valign="top"><p class="table">Emitted when a new part is found in the stream.
+                                  <tt>part</tt> is an instance of <tt>multipart.Part</tt>.</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table"><tt>"complete"</tt></p></td>
+<td align="left" valign="top"><p class="table"></p></td>
+<td align="left" valign="top"><p class="table">Emitted when the end of the stream is reached.</p></td>
+</tr>
+</tbody>
+</table>
+</div>
+<h4 id="_tt_multipart_part_tt"><tt>multipart.Part</tt></h4>
+<div class="tableblock">
+<table rules="all"
+width="100%"
+frame="border"
+cellspacing="0" cellpadding="4">
+<col width="7%" />
+<col width="15%" />
+<col width="76%" />
+<thead>
+<tr>
+<th align="left" valign="top">Event           </th>
+<th align="left" valign="top"> Parameters   </th>
+<th align="left" valign="top"> Notes</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="left" valign="top"><p class="table"><tt>"body"</tt></p></td>
+<td align="left" valign="top"><p class="table"><tt>chunk</tt></p></td>
+<td align="left" valign="top"><p class="table">Emitted when a chunk of body is read.</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table"><tt>"complete"</tt></p></td>
+<td align="left" valign="top"><p class="table"></p></td>
+<td align="left" valign="top"><p class="table">Emitted when the end of the part is reached.</p></td>
+</tr>
+</tbody>
+</table>
+</div>
 <h3 id="_tcp">TCP</h3><div style="clear:left"></div>
 <div class="paragraph"><p>To use the TCP server and client one must <tt>require("/tcp.js")</tt> or
 <tt>include("/tcp.js")</tt>.</p></div>
@ -2029,7 +2139,7 @@ init (Handle&lt;Object&gt; target)
 <div id="footer">
 <div id="footer-text">
 Version 0.1.13<br />
-Last updated 2009-09-30 23:15:59 CEST
+Last updated 2009-10-03 18:02:36 CEST
 </div>
 </div>
 </body>
--- a/doc/api.txt
+++ b/doc/api.txt
@ -565,8 +565,6 @@ Objects returned from +node.fs.stat()+ are of this type.

 +stats.isSocket()+:: ...

-
-
 === HTTP

 To use the HTTP server and client one must +require("/http.js")+ or
@ -942,6 +940,62 @@ After emitted no other events will be emitted on the response.
 +response.client+ ::
  A reference to the +http.Client+ that this response belongs to.

+=== Multipart Parsing
+
+A library to parse HTTP requests with +multipart/form-data+ is included with
+Node.  To use it, +require("/multipart.js")+.
+
+multipart.parse(options)+ ::
+  - on success: Returns an object where each key holds the value of one part of
+                the stream. +options+ can either be an instance of
+                +http.ServerRequest+ or an object containing a 'boundary' and a
+                'data' key.
+  - on error: no parameters.
+
+==== +multipart.Stream+
+
+Here is an example for parsing a +multipart/form-data+ request:
+
+----------------------------------------
+var multipart = require('/multipart.js');
+var stream = new multipart.Stream(options);
+var parts = {};
+
+stream.addListener('part', function (part) {
+  var name = part.headers['Content-Disposition'].name;
+  var buffer = '';
+
+  part.addListener('body', function(chunk) {
+    buffer = buffer + chunk;
+  });
+
+  part.addListener('complete', function() {
+    parts[name] = buffer;
+  });
+});
+
+stream.addListener('complete', function() {
+  // The parts object now contains all parts and data
+});
+----------------------------------------
+
+
+[cols="1,2,10",options="header"]
+|=========================================================
+|Event           | Parameters   | Notes
+|+"part"+        | +part+       | Emitted when a new part is found in the stream.
+                                  +part+ is an instance of +multipart.Part+.
+|+"complete"+    |              | Emitted when the end of the stream is reached.
+|=========================================================
+
+==== +multipart.Part+
+
+[cols="1,2,10",options="header"]
+|=========================================================
+|Event           | Parameters   | Notes
+|+"body"+        | +chunk+      | Emitted when a chunk of body is read.
+|+"complete"+    |              | Emitted when the end of the part is reached.
+|=========================================================


 === TCP
--- a/doc/api.xml
+++ b/doc/api.xml
@ -1609,6 +1609,121 @@ After emitted no other events will be emitted on the response.</simpara></entry>
 </variablelist>
 </refsect3>
 </refsect2>
+<refsect2 id="_multipart_parsing">
+<title>Multipart Parsing</title>
+<simpara>A library to parse HTTP requests with <literal>multipart/form-data</literal> is included with
+Node.  To use it, <literal>require("/multipart.js")</literal>.</simpara>
+<variablelist>
+<varlistentry>
+<term>
+<literal>multipart.parse(options)</literal> 
+</term>
+<listitem>
+<itemizedlist>
+<listitem>
+<simpara>
+on success: Returns an object where each key holds the value of one part of
+                the stream. <literal>options</literal> can either be an instance of
+                <literal>http.ServerRequest</literal> or an object containing a <emphasis>boundary</emphasis> and a
+                <emphasis>data</emphasis> key.
+</simpara>
+</listitem>
+<listitem>
+<simpara>
+on error: no parameters.
+</simpara>
+</listitem>
+</itemizedlist>
+</listitem>
+</varlistentry>
+</variablelist>
+<refsect3 id="_literal_multipart_stream_literal">
+<title><literal>multipart.Stream</literal></title>
+<simpara>Here is an example for parsing a <literal>multipart/form-data</literal> request:</simpara>
+<screen>var multipart = require('/multipart.js');
+var stream = new multipart.Stream(options);
+var parts = {};
+
+stream.addListener('part', function (part) {
+  var name = part.headers['Content-Disposition'].name;
+  var buffer = '';
+
+  part.addListener('body', function(chunk) {
+    buffer = buffer + chunk;
+  });
+
+  part.addListener('complete', function() {
+    parts[name] = buffer;
+  });
+});
+
+stream.addListener('complete', function() {
+  // The parts object now contains all parts and data
+});</screen>
+<informaltable
+frame="all"
+rowsep="1" colsep="1"
+>
+<tgroup cols="3">
+<colspec colname="col_1" colwidth="7*"/>
+<colspec colname="col_2" colwidth="15*"/>
+<colspec colname="col_3" colwidth="76*"/>
+<thead>
+<row>
+<entry align="left" valign="top">Event           </entry>
+<entry align="left" valign="top"> Parameters   </entry>
+<entry align="left" valign="top"> Notes</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry align="left" valign="top"><simpara><literal>"part"</literal></simpara></entry>
+<entry align="left" valign="top"><simpara><literal>part</literal></simpara></entry>
+<entry align="left" valign="top"><simpara>Emitted when a new part is found in the stream.
+                                  <literal>part</literal> is an instance of <literal>multipart.Part</literal>.</simpara></entry>
+</row>
+<row>
+<entry align="left" valign="top"><simpara><literal>"complete"</literal></simpara></entry>
+<entry align="left" valign="top"><simpara></simpara></entry>
+<entry align="left" valign="top"><simpara>Emitted when the end of the stream is reached.</simpara></entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+</refsect3>
+<refsect3 id="_literal_multipart_part_literal">
+<title><literal>multipart.Part</literal></title>
+<informaltable
+frame="all"
+rowsep="1" colsep="1"
+>
+<tgroup cols="3">
+<colspec colname="col_1" colwidth="7*"/>
+<colspec colname="col_2" colwidth="15*"/>
+<colspec colname="col_3" colwidth="76*"/>
+<thead>
+<row>
+<entry align="left" valign="top">Event           </entry>
+<entry align="left" valign="top"> Parameters   </entry>
+<entry align="left" valign="top"> Notes</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry align="left" valign="top"><simpara><literal>"body"</literal></simpara></entry>
+<entry align="left" valign="top"><simpara><literal>chunk</literal></simpara></entry>
+<entry align="left" valign="top"><simpara>Emitted when a chunk of body is read.</simpara></entry>
+</row>
+<row>
+<entry align="left" valign="top"><simpara><literal>"complete"</literal></simpara></entry>
+<entry align="left" valign="top"><simpara></simpara></entry>
+<entry align="left" valign="top"><simpara>Emitted when the end of the part is reached.</simpara></entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+</refsect3>
+</refsect2>
 <refsect2 id="_tcp">
 <title>TCP</title>
 <simpara>To use the TCP server and client one must <literal>require("/tcp.js")</literal> or
--- a/doc/node.1
+++ b/doc/node.1
@ -1,11 +1,11 @@
 .\"     Title: node
 .\"    Author: 
 .\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
-.\"      Date: 09/30/2009
+.\"      Date: 10/03/2009
 .\"    Manual: 
 .\"    Source: 
 .\"
-.TH "NODE" "1" "09/30/2009" "" ""
+.TH "NODE" "1" "10/03/2009" "" ""
 .\" disable hyphenation
 .nh
 .\" disable justification (adjust text to left margin only)
@ -1374,6 +1374,139 @@ http\.Client
 that this response belongs to\.
 .RE
 .RE
+.SS "Multipart Parsing"
+A library to parse HTTP requests with multipart/form\-data is included with Node\. To use it, require("/multipart\.js")\.
+.PP
+multipart\.parse(options)
+.RS 4
+.sp
+.RS 4
+\h'-04'\(bu\h'+03'on success: Returns an object where each key holds the value of one part of the stream\.
+options
+can either be an instance of
+http\.ServerRequest
+or an object containing a
+\fIboundary\fR
+and a
+\fIdata\fR
+key\.
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+03'on error: no parameters\.
+.RE
+.RE
+.sp
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+multipart.Stream
+.RS
+Here is an example for parsing a multipart/form\-data request:
+.sp
+.sp
+.RS 4
+.nf
+var multipart = require(\'/multipart\.js\');
+var stream = new multipart\.Stream(options);
+var parts = {};
+
+stream\.addListener(\'part\', function (part) {
+  var name = part\.headers[\'Content\-Disposition\']\.name;
+  var buffer = \'\';
+
+  part\.addListener(\'body\', function(chunk) {
+    buffer = buffer + chunk;
+  });
+
+  part\.addListener(\'complete\', function() {
+    parts[name] = buffer;
+  });
+});
+
+stream\.addListener(\'complete\', function() {
+  // The parts object now contains all parts and data
+});
+.fi
+.RE
+.TS
+allbox tab(:);
+ltB ltB ltB.
+T{
+Event
+T}:T{
+Parameters
+T}:T{
+Notes
+T}
+.T&
+lt lt lt
+lt lt lt.
+T{
+"part"
+.sp
+T}:T{
+part
+.sp
+T}:T{
+Emitted when a new part is found in the stream\. part is an instance of multipart\.Part\.
+.sp
+T}
+T{
+"complete"
+.sp
+T}:T{
+.sp
+T}:T{
+Emitted when the end of the stream is reached\.
+.sp
+T}
+.TE
+.sp
+.RE
+.sp
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+multipart.Part
+.RS
+.TS
+allbox tab(:);
+ltB ltB ltB.
+T{
+Event
+T}:T{
+Parameters
+T}:T{
+Notes
+T}
+.T&
+lt lt lt
+lt lt lt.
+T{
+"body"
+.sp
+T}:T{
+chunk
+.sp
+T}:T{
+Emitted when a chunk of body is read\.
+.sp
+T}
+T{
+"complete"
+.sp
+T}:T{
+.sp
+T}:T{
+Emitted when the end of the part is reached\.
+.sp
+T}
+.TE
+.sp
+.RE
 .SS "TCP"
 To use the TCP server and client one must require("/tcp\.js") or include("/tcp\.js")\.
 .sp
--- a/lib/multipart.js
+++ b/lib/multipart.js
@ -1,5 +1,30 @@
+exports.parse = function(options) {
+  var stream = new exports.Stream(options);
+  var promise = new node.Promise();
+
+  var parts = {};
+  stream.addListener('part', function(part) {
+    var name = part.headers['Content-Disposition'].name;
+    var buffer = '';
+
+    part.addListener('body', function(chunk) {
+      buffer = buffer + chunk;
+    });
+
+    part.addListener('complete', function() {
+      parts[name] = buffer;
+    });
+  });
+
+  stream.addListener('complete', function() {
+    promise.emitSuccess(parts);
+  });
+
+  return promise;
+};
+
 exports.Stream = function(options) {
- node.EventEmitter.call(this);
+  node.EventEmitter.call(this);

  this.init(options);
 };
@ -37,6 +62,7 @@ proto.init = function(options) {
      });
  } else {
    this.boundary = options.boundary;
+    this.write(options.data || '');
  }
 };