feat: add option to store files or not

Author: leonardovillela

README.md

@@ -64,7 +64,8 @@ _**Note: v2 is coming soon!**_
 ## Highlights
 
 - [Fast (~900-2500 mb/sec)](#benchmarks) & streaming multipart parser
-- Automatically writing file uploads to disk (soon optionally)
+- Automatically writing file uploads to disk (optional, see
+  [`options.storeFiles`](#options))
 - [Plugins API](#useplugin-plugin) - allowing custom parsers and plugins
 - Low memory footprint
 - Graceful error handling
@@ -310,8 +311,8 @@ const form = new Formidable(options);
 
 ### Options
 
-See it's defaults in [src/Formidable.js DEFAULT_OPTIONS](./src/Formidable.js) (the
-`DEFAULT_OPTIONS` constant).
+See it's defaults in [src/Formidable.js DEFAULT_OPTIONS](./src/Formidable.js)
+(the `DEFAULT_OPTIONS` constant).
 
 - `options.encoding` **{string}** - default `'utf-8'`; sets encoding for
   incoming form fields,
@@ -334,6 +335,8 @@ See it's defaults in [src/Formidable.js DEFAULT_OPTIONS](./src/Formidable.js) (t
   for incoming files, set this to some hash algorithm, see
   [crypto.createHash](https://nodejs.org/api/crypto.html#crypto_crypto_createhash_algorithm_options)
   for available algorithms
+- `options.storeFiles` **{boolean}** - default `true`; to store uploaded file(s)
+  in `uploadDir` on host machine or not and only parse the file(s).
 - `options.multiples` **{boolean}** - default `false`; when you call the
   `.parse` method, the `files` argument (of the callback) will contain arrays of
   files for inputs which submit multiple files using the HTML5 `multiple`
@@ -636,8 +639,8 @@ form.on('end', () => {});
 
 If the documentation is unclear or has a typo, please click on the page's `Edit`
 button (pencil icon) and suggest a correction. If you would like to help us fix
-a bug or add a new feature, please check our
-[Contributing Guide][contributing-url]. Pull requests are welcome!
+a bug or add a new feature, please check our [Contributing
+Guide][contributing-url]. Pull requests are welcome!
 
 Thanks goes to these wonderful people
 ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

examples/not-store-files.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const http = require('http');
+const formidable = require('../src/index');
+
+const server = http.createServer((req, res) => {
+  if (req.url === '/api/upload' && req.method.toLowerCase() === 'post') {
+    // parse a file upload
+    const form = formidable({ multiples: true, storeFiles: false });
+
+    form.parse(req, (err, fields, files) => {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ fields, files }, null, 2));
+    });
+
+    return;
+  }
+
+  // show a file upload form
+  res.writeHead(200, { 'Content-Type': 'text/html' });
+  res.end(`
+    <h2>With Node.js <code>"http"</code> module</h2>
+    <form action="/api/upload" enctype="multipart/form-data" method="post">
+      <div>Text field title: <input type="text" name="title" /></div>
+      <div>File: <input type="file" name="multipleFiles" multiple="multiple" /></div>
+      <input type="submit" value="Upload" />
+    </form>
+  `);
+});
+
+server.listen(3000, () => {
+  console.log('Server listening on http://localhost:3000 ...');
+});

src/Formidable.js

@@ -24,11 +24,13 @@ const DEFAULT_OPTIONS = {
   encoding: 'utf-8',
   hash: false,
   uploadDir: os.tmpdir(),
+  storeFiles: true,
   multiples: false,
   enabledPlugins: ['octetstream', 'querystring', 'multipart', 'json'],
 };
 
-const File = require('./File');
+const PersistentFile = require('./PersistentFile');
+const VolatileFile = require('./VolatileFile');
 const DummyParser = require('./parsers/Dummy');
 const MultipartParser = require('./parsers/Multipart');
 
@@ -138,11 +140,11 @@ class IncomingForm extends EventEmitter {
       const fields = {};
       let mockFields = '';
       const files = {};
-      
+
       this.on('field', (name, value) => {
         if (this.options.multiples) {
-          let mObj = { [name] : value };
-          mockFields = mockFields + '&' + qs.stringify(mObj);
+          const mObj = { [name]: value };
+          mockFields = `${mockFields}&${qs.stringify(mObj)}`;
         } else {
           fields[name] = value;
         }
@@ -295,11 +297,10 @@ class IncomingForm extends EventEmitter {
 
     this._flushing += 1;
 
-    const file = new File({
+    const file = this._newFile({
       path: this._rename(part),
-      name: part.filename,
-      type: part.mime,
-      hash: this.options.hash,
+      filename: part.filename,
+      mime: part.mime,
     });
     file.on('error', (err) => {
       this._error(err);
@@ -420,7 +421,7 @@ class IncomingForm extends EventEmitter {
 
     if (Array.isArray(this.openedFiles)) {
       this.openedFiles.forEach((file) => {
-        file._writeStream.destroy();
+        file.destroy();
         setTimeout(fs.unlink, 0, file.path, () => {});
       });
     }
@@ -443,6 +444,21 @@ class IncomingForm extends EventEmitter {
     return new MultipartParser(this.options);
   }
 
+  _newFile({ path: filePath, filename: name, mime: type }) {
+    return this.options.storeFiles
+      ? new PersistentFile({
+          path: filePath,
+          name,
+          type,
+          hash: this.options.hash,
+        })
+      : new VolatileFile({
+          name,
+          type,
+          hash: this.options.hash,
+        });
+  }
+
   _getFileName(headerValue) {
     // matches either a quoted-string or a token (RFC 2616 section 19.5.1)
     const m = headerValue.match(

src/File.js renamed to src/PersistentFile.js

@@ -6,7 +6,7 @@ const fs = require('fs');
 const crypto = require('crypto');
 const { EventEmitter } = require('events');
 
-class File extends EventEmitter {
+class PersistentFile extends EventEmitter {
   constructor(properties) {
     super();
 
@@ -56,7 +56,7 @@ class File extends EventEmitter {
   }
 
   toString() {
-    return `File: ${this.name}, Path: ${this.path}`;
+    return `PersistentFile: ${this.name}, Path: ${this.path}`;
   }
 
   write(buffer, cb) {
@@ -86,6 +86,10 @@ class File extends EventEmitter {
       cb();
     });
   }
+
+  destroy() {
+    this._writeStream.destroy();
+  }
 }
 
-module.exports = File;
+module.exports = PersistentFile;

src/VolatileFile.js

@@ -0,0 +1,73 @@
+/* eslint-disable no-underscore-dangle */
+
+'use strict';
+
+const crypto = require('crypto');
+const { EventEmitter } = require('events');
+
+class VolatileFile extends EventEmitter {
+  constructor(properties) {
+    super();
+
+    this.size = 0;
+    this.name = null;
+    this.type = null;
+    this.hash = null;
+
+    // eslint-disable-next-line guard-for-in, no-restricted-syntax
+    for (const key in properties) {
+      this[key] = properties[key];
+    }
+
+    if (typeof this.hash === 'string') {
+      this.hash = crypto.createHash(properties.hash);
+    } else {
+      this.hash = null;
+    }
+  }
+
+  // eslint-disable-next-line class-methods-use-this
+  open() {}
+
+  // eslint-disable-next-line class-methods-use-this
+  destroy() {}
+
+  toJSON() {
+    const json = {
+      size: this.size,
+      name: this.name,
+      type: this.type,
+      length: this.length,
+      filename: this.filename,
+      mime: this.mime,
+    };
+    if (this.hash && this.hash !== '') {
+      json.hash = this.hash;
+    }
+    return json;
+  }
+
+  toString() {
+    return `VolatileFile: ${this.name}`;
+  }
+
+  write(buffer, cb) {
+    if (this.hash) {
+      this.hash.update(buffer);
+    }
+
+    this.size += buffer.length;
+    this.emit('progress', this.size);
+    cb();
+  }
+
+  end(cb) {
+    if (this.hash) {
+      this.hash = this.hash.digest('hex');
+    }
+    this.emit('end');
+    cb();
+  }
+}
+
+module.exports = VolatileFile;

src/index.js

@@ -1,6 +1,7 @@
 'use strict';
 
-const File = require('./File');
+const PersistentFile = require('./PersistentFile');
+const VolatileFile = require('./VolatileFile');
 const Formidable = require('./Formidable');
 
 const plugins = require('./plugins/index');
@@ -11,7 +12,9 @@ const parsers = require('./parsers/index');
 const formidable = (...args) => new Formidable(...args);
 
 module.exports = Object.assign(formidable, {
-  File,
+  File: PersistentFile,
+  PersistentFile,
+  VolatileFile,
   Formidable,
   formidable,
 

src/plugins/octetstream.js

@@ -2,7 +2,6 @@
 
 'use strict';
 
-const File = require('../File');
 const OctetStreamParser = require('../parsers/OctetStream');
 
 // the `options` is also available through the `options` / `formidable.options`
@@ -28,11 +27,10 @@ function init(_self, _opts) {
   const filename = this.headers['x-file-name'];
   const mime = this.headers['content-type'];
 
-  const file = new File({
+  const file = this._newFile({
     path: this._uploadPath(filename),
-    name: filename,
-    type: mime,
-    hash: this.options.hash,
+    filename,
+    mime,
   });
 
   this.emit('fileBegin', filename, file);

test/integration/test-store-files-option.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const http = require('http');
+const path = require('path');
+const assert = require('assert');
+
+const formidable = require('../../src/index');
+
+const PORT = 13532;
+const UPLOAD_DIR = path.join(os.tmpdir(), 'test-store-files-option');
+const testFilePath = path.join(
+  path.dirname(__dirname),
+  'fixture',
+  'file',
+  'binaryfile.tar.gz',
+);
+
+const server = http.createServer((req, res) => {
+  if (!fs.existsSync(UPLOAD_DIR)) {
+    fs.mkdirSync(UPLOAD_DIR);
+  }
+  const form = formidable({ storeFiles: false, uploadDir: UPLOAD_DIR });
+
+  form.parse(req, (err, fields, files) => {
+    assert.strictEqual(Object.keys(files).length, 1);
+    const { file } = files;
+
+    assert.strictEqual(file.size, 301);
+    assert.ok(file.path === undefined);
+
+    const dirFiles = fs.readdirSync(UPLOAD_DIR);
+    assert.ok(dirFiles.length === 0);
+
+    res.end();
+    server.close();
+  });
+});
+
+server.listen(PORT, (err) => {
+  const choosenPort = server.address().port;
+  const url = `http://localhost:${choosenPort}`;
+  console.log('Server up and running at:', url);
+
+  assert(!err, 'should not have error, but be falsey');
+
+  const request = http.request({
+    port: PORT,
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/octet-stream',
+    },
+  });
+
+  fs.createReadStream(testFilePath).pipe(request);
+});

test/unit/file.test.js renamed to test/unit/persistent-file.test.js

@@ -1,9 +1,9 @@
 'use strict';
 
-const { File } = require('../../src/index');
+const PersistentFile = require('../../src/PersistentFile');
 
 const now = new Date();
-const file = new File({
+const file = new PersistentFile({
   size: 1024,
   path: '/tmp/cat.png',
   name: 'cat.png',
@@ -13,7 +13,7 @@ const file = new File({
   mime: 'image/png',
 });
 
-test('File#toJSON()', () => {
+test('PersistentFile#toJSON()', () => {
   const obj = file.toJSON();
   const len = Object.keys(obj).length;