feat: response.attachment append a parameter: options from contentDis…

…position (#1240)

docs/api/response.md

@@ -271,11 +271,11 @@ ctx.redirect('/cart');
 ctx.body = 'Redirecting to shopping cart';
 ```
 
-### response.attachment([filename])
+### response.attachment([filename], [options])
 
  Set `Content-Disposition` to "attachment" to signal the client
  to prompt for download. Optionally specify the `filename` of the
- download.
+ download and some [options](https://github.com/jshttp/content-disposition#options).
 
 ### response.headerSent
 

lib/response.js

@@ -285,9 +285,9 @@ module.exports = {
  * @api public
  */
 
- attachment(filename) {
+ attachment(filename, options) {
  if (filename) this.type = extname(filename);
- this.set('Content-Disposition', contentDisposition(filename));
+ this.set('Content-Disposition', contentDisposition(filename, options));
  },
 
  /**

test/response/attachment.js

@@ -48,3 +48,138 @@ describe('ctx.attachment([filename])', () => {
  });
  });
 });
+
+// reference test case of content-disposition module
+describe('contentDisposition(filename, options)', () => {
+ describe('with "fallback" option', () => {
+ it('should require a string or Boolean', () => {
+ const ctx = context();
+ assert.throws(() => { ctx.attachment('plans.pdf', { fallback: 42 }); },
+ /fallback.*string/);
+ });
+
+ it('should default to true', () => {
+ const ctx = context();
+ ctx.attachment('€ rates.pdf');
+ assert.equal(ctx.response.header['content-disposition'],
+ 'attachment; filename="? rates.pdf"; filename*=UTF-8\'\'%E2%82%AC%20rates.pdf');
+ });
+
+ describe('when "false"', () => {
+ it('should not generate ISO-8859-1 fallback', () => {
+ const ctx = context();
+ ctx.attachment('£ and € rates.pdf', { fallback: false });
+ assert.equal(ctx.response.header['content-disposition'],
+ 'attachment; filename*=UTF-8\'\'%C2%A3%20and%20%E2%82%AC%20rates.pdf');
+ });
+
+ it('should keep ISO-8859-1 filename', () => {
+ const ctx = context();
+ ctx.attachment('£ rates.pdf', { fallback: false });
+ assert.equal(ctx.response.header['content-disposition'],
+ 'attachment; filename="£ rates.pdf"');
+ });
+ });
+
+ describe('when "true"', () => {
+ it('should generate ISO-8859-1 fallback', () => {
+ const ctx = context();
+ ctx.attachment('£ and € rates.pdf', { fallback: true });
+ assert.equal(ctx.response.header['content-disposition'],
+ 'attachment; filename="£ and ? rates.pdf"; filename*=UTF-8\'\'%C2%A3%20and%20%E2%82%AC%20rates.pdf');
+ });
+
+ it('should pass through ISO-8859-1 filename', () => {
+ const ctx = context();
+ ctx.attachment('£ rates.pdf', { fallback: true });
+ assert.equal(ctx.response.header['content-disposition'],
+ 'attachment; filename="£ rates.pdf"');
+ });
+ });
+
+ describe('when a string', () => {
+ it('should require an ISO-8859-1 string', () => {
+ const ctx = context();
+ assert.throws(() => { ctx.attachment('€ rates.pdf', { fallback: '€ rates.pdf' }); },
+ /fallback.*iso-8859-1/i);
+ });
+
+ it('should use as ISO-8859-1 fallback', () => {
+ const ctx = context();
+ ctx.attachment('£ and € rates.pdf', { fallback: '£ and EURO rates.pdf' });
+ assert.equal(ctx.response.header['content-disposition'],
+ 'attachment; filename="£ and EURO rates.pdf"; filename*=UTF-8\'\'%C2%A3%20and%20%E2%82%AC%20rates.pdf');
+ });
+
+ it('should use as fallback even when filename is ISO-8859-1', () => {
+ const ctx = context();
+ ctx.attachment('"£ rates".pdf', { fallback: '£ rates.pdf' });
+ assert.equal(ctx.response.header['content-disposition'],
+ 'attachment; filename="£ rates.pdf"; filename*=UTF-8\'\'%22%C2%A3%20rates%22.pdf');
+ });
+
+ it('should do nothing if equal to filename', () => {
+ const ctx = context();
+ ctx.attachment('plans.pdf', { fallback: 'plans.pdf' });
+ assert.equal(ctx.response.header['content-disposition'],
+ 'attachment; filename="plans.pdf"');
+ });
+
+ it('should use the basename of the string', () => {
+ const ctx = context();
+ ctx.attachment('€ rates.pdf', { fallback: '/path/to/EURO rates.pdf' });
+ assert.equal(ctx.response.header['content-disposition'],
+ 'attachment; filename="EURO rates.pdf"; filename*=UTF-8\'\'%E2%82%AC%20rates.pdf');
+ });
+
+ it('should do nothing without filename option', () => {
+ const ctx = context();
+ ctx.attachment(undefined, { fallback: 'plans.pdf' });
+ assert.equal(ctx.response.header['content-disposition'],
+ 'attachment');
+ });
+ });
+ });
+
+ describe('with "type" option', () => {
+ it('should default to attachment', () => {
+ const ctx = context();
+ ctx.attachment();
+ assert.equal(ctx.response.header['content-disposition'],
+ 'attachment');
+ });
+
+ it('should require a string', () => {
+ const ctx = context();
+ assert.throws(() => { ctx.attachment(undefined, { type: 42 }); },
+ /invalid type/);
+ });
+
+ it('should require a valid type', () => {
+ const ctx = context();
+ assert.throws(() => { ctx.attachment(undefined, { type: 'invlaid;type' }); },
+ /invalid type/);
+ });
+
+ it('should create a header with inline type', () => {
+ const ctx = context();
+ ctx.attachment(undefined, { type: 'inline' });
+ assert.equal(ctx.response.header['content-disposition'],
+ 'inline');
+ });
+
+ it('should create a header with inline type & filename', () => {
+ const ctx = context();
+ ctx.attachment('plans.pdf', { type: 'inline' });
+ assert.equal(ctx.response.header['content-disposition'],
+ 'inline; filename="plans.pdf"');
+ });
+
+ it('should normalize type', () => {
+ const ctx = context();
+ ctx.attachment(undefined, { type: 'INLINE' });
+ assert.equal(ctx.response.header['content-disposition'],
+ 'inline');
+ });
+ });
+});