@eggjs/multipart 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-present Alibaba Group Holding Limited and other contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,444 @@
+# @eggjs/multipart
+
+[![NPM version][npm-image]][npm-url]
+[![Node.js CI](https://github.com/eggjs/multipart/actions/workflows/nodejs.yml/badge.svg)](https://github.com/eggjs/multipart/actions/workflows/nodejs.yml)
+[![Test coverage][codecov-image]][codecov-url]
+[![Known Vulnerabilities][snyk-image]][snyk-url]
+[![npm download][download-image]][download-url]
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://makeapullrequest.com)
+![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/eggjs/multipart)
+
+[npm-image]: https://img.shields.io/npm/v/@eggjs/multipart.svg?style=flat-square
+[npm-url]: https://npmjs.org/package/@eggjs/multipart
+[codecov-image]: https://codecov.io/github/eggjs/multipart/coverage.svg?branch=master
+[codecov-url]: https://codecov.io/github/eggjs/multipart?branch=master
+[snyk-image]: https://snyk.io/test/npm/@eggjs/multipart/badge.svg?style=flat-square
+[snyk-url]: https://snyk.io/test/npm/@eggjs/multipart
+[download-image]: https://img.shields.io/npm/dm/@eggjs/multipart.svg?style=flat-square
+[download-url]: https://npmjs.org/package/@eggjs/multipart
+
+Use [co-busboy](https://github.com/cojs/busboy) to upload file by streaming and
+process it without save to disk(using the `stream` mode).
+
+Just use `ctx.multipart()` to got file stream, then pass to image processing module such as `gm` or upload to cloud storage such as `oss`.
+
+## Whitelist of file extensions
+
+For security, if uploading file extension is not in white list, will response as `400 Bad request`.
+
+Default Whitelist:
+
+```js
+const whitelist = [
+  // images
+  '.jpg', '.jpeg', // image/jpeg
+  '.png', // image/png, image/x-png
+  '.gif', // image/gif
+  '.bmp', // image/bmp
+  '.wbmp', // image/vnd.wap.wbmp
+  '.webp',
+  '.tif',
+  '.psd',
+  // text
+  '.svg',
+  '.js', '.jsx',
+  '.json',
+  '.css', '.less',
+  '.html', '.htm',
+  '.xml',
+  // tar
+  '.zip',
+  '.gz', '.tgz', '.gzip',
+  // video
+  '.mp3',
+  '.mp4',
+  '.avi',
+];
+```
+
+### fileSize
+
+The default fileSize that multipart can accept is `10mb`. if you upload a large file, you should specify this config.
+
+```js
+// config/config.default.js
+exports.multipart = {
+  fileSize: '50mb',
+};
+```
+
+### Custom Config
+
+Developer can custom additional file extensions:
+
+```js
+// config/config.default.js
+exports.multipart = {
+  // will append to whilelist
+  fileExtensions: [
+    '.foo',
+    '.apk',
+  ],
+};
+```
+
+Can also **override** built-in whitelist, such as only allow png:
+
+```js
+// config/config.default.js
+exports.multipart = {
+  whitelist: [
+    '.png',
+  ],
+};
+```
+
+Or by function：
+
+```js
+exports.multipart = {
+  whitelist: (filename) => [ '.png' ].includes(path.extname(filename) || '')
+};
+```
+
+**Note: if define `whitelist`, then `fileExtensions` will be ignored.**
+
+## Examples
+
+More examples please follow:
+
+- [Handle multipart request in `stream` mode](https://github.com/eggjs/examples/tree/master/multipart)
+- [Handle multipart request in `file` mode](https://github.com/eggjs/examples/tree/master/multipart-file-mode)
+
+## `file` mode: the easy way
+
+If you don't know the [Node.js Stream](https://nodejs.org/dist/latest-v18.x/docs/api/stream.html) work,
+maybe you should use the `file` mode to get started.
+
+The usage very similar to [bodyParser](https://eggjs.org/en/basics/controller.html#body).
+
+- `ctx.request.body`: Get all the multipart fields and values, except `file`.
+- `ctx.request.files`: Contains all `file` from the multipart request, it's an Array object.
+
+**WARNING: you should remove the temporary upload files after you use it**,
+the `async ctx.cleanupRequestFiles()` method will be very helpful.
+
+### Enable `file` mode on config
+
+You need to set `config.multipart.mode = 'file'` to enable `file` mode:
+
+```js
+// config/config.default.js
+exports.multipart = {
+  mode: 'file',
+};
+```
+
+After `file` mode enable, egg will remove the old temporary files(don't include today's files) on `04:30 AM` every day by default.
+
+```js
+config.multipart = {
+  mode: 'file',
+  tmpdir: path.join(os.tmpdir(), 'egg-multipart-tmp', appInfo.name),
+  cleanSchedule: {
+    // run tmpdir clean job on every day 04:30 am
+    // cron style see https://github.com/eggjs/egg-schedule#cron-style-scheduling
+    cron: '0 30 4 * * *',
+    disable: false,
+  },
+};
+```
+
+Default will use the last field which has same name, if need the all fields value, please set `allowArrayField` in config.
+
+```js
+// config/config.default.js
+exports.multipart = {
+  mode: 'file',
+  allowArrayField: true,
+};
+```
+
+### Upload One File
+
+```html
+<form method="POST" action="/upload?_csrf={{ ctx.csrf | safe }}" enctype="multipart/form-data">
+  title: <input name="title" />
+  file: <input name="file" type="file" />
+  <button type="submit">Upload</button>
+</form>
+```
+
+Controller which hanlder `POST /upload`:
+
+```js
+// app/controller/upload.js
+const Controller = require('egg').Controller;
+const fs = require('mz/fs');
+
+module.exports = class extends Controller {
+  async upload() {
+    const { ctx } = this;
+    const file = ctx.request.files[0];
+    const name = 'egg-multipart-test/' + path.basename(file.filename);
+    let result;
+    try {
+      // process file or upload to cloud storage
+      result = await ctx.oss.put(name, file.filepath);
+    } finally {
+      // remove tmp files and don't block the request's response
+      // cleanupRequestFiles won't throw error even remove file io error happen
+      ctx.cleanupRequestFiles();
+      // remove tmp files before send response
+      // await ctx.cleanupRequestFiles();
+    }
+
+    ctx.body = {
+      url: result.url,
+      // get all field values
+      requestBody: ctx.request.body,
+    };
+  }
+};
+```
+
+### Upload Multiple Files
+
+```html
+<form method="POST" action="/upload?_csrf={{ ctx.csrf | safe }}" enctype="multipart/form-data">
+  title: <input name="title" />
+  file1: <input name="file1" type="file" />
+  file2: <input name="file2" type="file" />
+  <button type="submit">Upload</button>
+</form>
+```
+
+Controller which hanlder `POST /upload`:
+
+```js
+// app/controller/upload.js
+const Controller = require('egg').Controller;
+const fs = require('mz/fs');
+
+module.exports = class extends Controller {
+  async upload() {
+    const { ctx } = this;
+    console.log(ctx.request.body);
+    console.log('got %d files', ctx.request.files.length);
+    for (const file of ctx.request.files) {
+      console.log('field: ' + file.fieldname);
+      console.log('filename: ' + file.filename);
+      console.log('encoding: ' + file.encoding);
+      console.log('mime: ' + file.mime);
+      console.log('tmp filepath: ' + file.filepath);
+      let result;
+      try {
+        // process file or upload to cloud storage
+        result = await ctx.oss.put('egg-multipart-test/' + file.filename, file.filepath);
+      } finally {
+        // remove tmp files and don't block the request's response
+        // cleanupRequestFiles won't throw error even remove file io error happen
+        ctx.cleanupRequestFiles([ file ]);
+      }
+      console.log(result);
+    }
+  }
+};
+```
+
+## `stream` mode: the hard way
+
+If you're well-known about know the Node.js Stream work, you should use the `stream` mode.
+
+### Use with `for await...of`
+
+```html
+<form method="POST" action="/upload?_csrf={{ ctx.csrf | safe }}" enctype="multipart/form-data">
+  title: <input name="title" />
+  file1: <input name="file1" type="file" />
+  file2: <input name="file2" type="file" />
+  <button type="submit">Upload</button>
+</form>
+```
+
+Controller which hanlder `POST /upload`:
+
+```js
+// app/controller/upload.js
+const { Controller } = require('egg');
+const fs = require('fs');
+const stream = require('stream');
+const util = require('util');
+const { randomUUID } = require('crypto');
+const pipeline = util.promisify(stream.pipeline);
+
+module.exports = class UploadController extends Controller {
+  async upload() {
+    const parts = this.ctx.multipart();
+    const fields = {};
+    const files = {};
+
+    for await (const part of parts) {
+      if (Array.isArray(part)) {
+        // fields
+        console.log('field: ' + part[0]);
+        console.log('value: ' + part[1]);
+      } else {
+        // otherwise, it's a stream
+        const { filename, fieldname, encoding, mime } = part;
+
+        console.log('field: ' + fieldname);
+        console.log('filename: ' + filename);
+        console.log('encoding: ' + encoding);
+        console.log('mime: ' + mime);
+
+        // how to handler?
+        // 1. save to tmpdir with pipeline
+        // 2. or send to oss
+        // 3. or just consume it with another for await
+
+        // WARNING: You should almost never use the origin filename as it could contain malicious input.
+        const targetPath = path.join(os.tmpdir(), randomUUID() + path.extname(filename));
+        await pipeline(part, createWriteStream(targetPath)); // use `pipeline` not `pipe`
+      }
+    }
+
+    this.ctx.body = 'ok';
+  }
+};
+```
+
+### Upload One File (DEPRECATED)
+
+You can got upload stream by `ctx.getFileStream*()`.
+
+```html
+<form method="POST" action="/upload?_csrf={{ ctx.csrf | safe }}" enctype="multipart/form-data">
+  title: <input name="title" />
+  file: <input name="file" type="file" />
+  <button type="submit">Upload</button>
+</form>
+```
+
+Controller which handler `POST /upload`:
+
+```js
+// app/controller/upload.js
+const path = require('node:path');
+const { sendToWormhole } = require('stream-wormhole');
+const { Controller } = require('egg');
+
+module.exports = class extends Controller {
+  async upload() {
+    const { ctx } = this;
+    // file not exists will response 400 error
+    const stream = await ctx.getFileStream();
+    const name = 'egg-multipart-test/' + path.basename(stream.filename);
+    // process file or upload to cloud storage
+    const result = await ctx.oss.put(name, stream);
+
+    ctx.body = {
+      url: result.url,
+      // process form fields by `stream.fields`
+      fields: stream.fields,
+    };
+  }
+
+  async uploadNotRequiredFile() {
+    const { ctx } = this;
+    // file not required
+    const stream = await ctx.getFileStream({ requireFile: false });
+    let result;
+    if (stream.filename) {
+      const name = 'egg-multipart-test/' + path.basename(stream.filename);
+      // process file or upload to cloud storage
+      const result = await ctx.oss.put(name, stream);
+    } else {
+      // must consume the empty stream
+      await sendToWormhole(stream);
+    }
+
+    ctx.body = {
+      url: result && result.url,
+      // process form fields by `stream.fields`
+      fields: stream.fields,
+    };
+  }
+};
+```
+
+### Upload Multiple Files (DEPRECATED)
+
+```html
+<form method="POST" action="/upload?_csrf={{ ctx.csrf | safe }}" enctype="multipart/form-data">
+  title: <input name="title" />
+  file1: <input name="file1" type="file" />
+  file2: <input name="file2" type="file" />
+  <button type="submit">Upload</button>
+</form>
+```
+
+Controller which hanlder `POST /upload`:
+
+```js
+// app/controller/upload.js
+const Controller = require('egg').Controller;
+
+module.exports = class extends Controller {
+  async upload() {
+    const { ctx } = this;
+    const parts = ctx.multipart();
+    let part;
+    while ((part = await parts()) != null) {
+      if (part.length) {
+        // arrays are busboy fields
+        console.log('field: ' + part[0]);
+        console.log('value: ' + part[1]);
+        console.log('valueTruncated: ' + part[2]);
+        console.log('fieldnameTruncated: ' + part[3]);
+      } else {
+        if (!part.filename) {
+          // user click `upload` before choose a file,
+          // `part` will be file stream, but `part.filename` is empty
+          // must handler this, such as log error.
+          continue;
+        }
+        // otherwise, it's a stream
+        console.log('field: ' + part.fieldname);
+        console.log('filename: ' + part.filename);
+        console.log('encoding: ' + part.encoding);
+        console.log('mime: ' + part.mime);
+        const result = await ctx.oss.put('egg-multipart-test/' + part.filename, part);
+        console.log(result);
+      }
+    }
+    console.log('and we are done parsing the form!');
+  }
+};
+```
+
+### Support `file` and `stream` mode in the same time
+
+If the default `mode` is `stream`, use the `fileModeMatch` options to match the request urls switch to `file` mode.
+
+```js
+config.multipart = {
+  mode: 'stream',
+  // let POST /upload_file request use the file mode, other requests use the stream mode.
+  fileModeMatch: /^\/upload_file$/,
+  // or glob
+  // fileModeMatch: '/upload_file',
+};
+```
+
+NOTICE: `fileModeMatch` options only work on `stream` mode.
+
+## License
+
+[MIT](LICENSE)
+
+## Contributors
+
+[![Contributors](https://contrib.rocks/image?repo=eggjs/multipart)](https://github.com/eggjs/multipart/graphs/contributors)
+
+Made with [contributors-img](https://contrib.rocks).

package/dist/commonjs/app/extend/context.d.ts

@@ -0,0 +1,110 @@
+import { Readable } from 'node:stream';
+import { Context } from '@eggjs/core';
+export interface EggFile {
+    field: string;
+    filename: string;
+    encoding: string;
+    mime: string;
+    filepath: string;
+}
+export interface MultipartFileStream extends Readable {
+    fields: Record<string, any>;
+    filename: string;
+    fieldname: string;
+    mime: string;
+    mimeType: string;
+    transferEncoding: string;
+    encoding: string;
+    truncated: boolean;
+}
+export interface MultipartOptions {
+    autoFields?: boolean;
+    /**
+     * required file submit, default is true
+     */
+    requireFile?: boolean;
+    /**
+     * default charset encoding
+     */
+    defaultCharset?: string;
+    /**
+     * compatible with defaultCharset
+     * @deprecated use `defaultCharset` instead
+     */
+    defCharset?: string;
+    defaultParamCharset?: string;
+    /**
+     * compatible with defaultParamCharset
+     * @deprecated use `defaultParamCharset` instead
+     */
+    defParamCharset?: string;
+    limits?: {
+        fieldNameSize?: number;
+        fieldSize?: number;
+        fields?: number;
+        fileSize?: number;
+        files?: number;
+        parts?: number;
+        headerPairs?: number;
+    };
+    checkFile?(fieldname: string, file: any, filename: string, encoding: string, mimetype: string): void | Error;
+}
+export default class MultipartContext extends Context {
+    /**
+     * create multipart.parts instance, to get separated files.
+     * @function Context#multipart
+     * @param {Object} [options] - override default multipart configurations
+     *  - {Boolean} options.autoFields
+     *  - {String} options.defaultCharset
+     *  - {String} options.defaultParamCharset
+     *  - {Object} options.limits
+     *  - {Function} options.checkFile
+     * @return {Yieldable | AsyncIterable<Yieldable>} parts
+     */
+    multipart(options?: MultipartOptions): AsyncIterable<MultipartFileStream>;
+    /**
+     * save request multipart data and files to `ctx.request`
+     * @function Context#saveRequestFiles
+     * @param {Object} options - { limits, checkFile, ... }
+     */
+    saveRequestFiles(options?: MultipartOptions): Promise<void>;
+    /**
+     * get upload file stream
+     * @example
+     * ```js
+     * const stream = await ctx.getFileStream();
+     * // get other fields
+     * console.log(stream.fields);
+     * ```
+     * @function Context#getFileStream
+     * @param {Object} options
+     *  - {Boolean} options.requireFile - required file submit, default is true
+     *  - {String} options.defaultCharset
+     *  - {String} options.defaultParamCharset
+     *  - {Object} options.limits
+     *  - {Function} options.checkFile
+     * @return {ReadStream} stream
+     * @since 1.0.0
+     * @deprecated Not safe enough, use `ctx.multipart()` instead
+     */
+    getFileStream(options?: MultipartOptions): Promise<MultipartFileStream>;
+    /**
+     * clean up request tmp files helper
+     * @function Context#cleanupRequestFiles
+     * @param {Array<String>} [files] - file paths need to cleanup, default is `ctx.request.files`.
+     */
+    cleanupRequestFiles(files?: EggFile[]): Promise<void>;
+}
+declare module '@eggjs/core' {
+    interface Request {
+        /**
+         * Files Object Array
+         */
+        files?: EggFile[];
+    }
+    interface Context {
+        saveRequestFiles(options?: MultipartOptions): Promise<void>;
+        getFileStream(options?: MultipartOptions): Promise<MultipartFileStream>;
+        cleanupRequestFiles(files?: EggFile[]): Promise<void>;
+    }
+}