3 * Copyright(c) 2014 Douglas Christopher Wilson
11 module.exports = contentDisposition
12 module.exports.parse = parse
15 * Module dependencies.
18 var basename = require('path').basename
21 * RegExp to match non attr-char, *after* encodeURIComponent (i.e. not including "%")
24 var encodeUriAttrCharRegExp = /[\x00-\x20"'\(\)*,\/:;<=>?@\[\\\]\{\}\x7f]/g
27 * RegExp to match percent encoding escape.
30 var hexEscapeRegExp = /%[0-9A-Fa-f]{2}/
31 var hexEscapeReplaceRegExp = /%([0-9A-Fa-f]{2})/g
34 * RegExp to match non-latin1 characters.
37 var nonLatin1RegExp = /[^\x20-\x7e\xa0-\xff]/g
40 * RegExp to match quoted-pair in RFC 2616
42 * quoted-pair = "\" CHAR
43 * CHAR = <any US-ASCII character (octets 0 - 127)>
46 var qescRegExp = /\\([\u0000-\u007f])/g;
49 * RegExp to match chars that must be quoted-pair in RFC 2616
52 var quoteRegExp = /([\\"])/g
55 * RegExp for various RFC 2616 grammar
57 * parameter = token "=" ( token | quoted-string )
58 * token = 1*<any CHAR except CTLs or separators>
59 * separators = "(" | ")" | "<" | ">" | "@"
60 * | "," | ";" | ":" | "\" | <">
61 * | "/" | "[" | "]" | "?" | "="
62 * | "{" | "}" | SP | HT
63 * quoted-string = ( <"> *(qdtext | quoted-pair ) <"> )
64 * qdtext = <any TEXT except <">>
65 * quoted-pair = "\" CHAR
66 * CHAR = <any US-ASCII character (octets 0 - 127)>
67 * TEXT = <any OCTET except CTLs, but including LWS>
68 * LWS = [CRLF] 1*( SP | HT )
70 * CR = <US-ASCII CR, carriage return (13)>
71 * LF = <US-ASCII LF, linefeed (10)>
72 * SP = <US-ASCII SP, space (32)>
73 * HT = <US-ASCII HT, horizontal-tab (9)>
74 * CTL = <any US-ASCII control character (octets 0 - 31) and DEL (127)>
75 * OCTET = <any 8-bit sequence of data>
78 var paramRegExp = /; *([!#$%&'\*\+\-\.0-9A-Z\^_`a-z\|~]+) *= *("(?:[ !\x23-\x5b\x5d-\x7e\x80-\xff]|\\[\x20-\x7e])*"|[!#$%&'\*\+\-\.0-9A-Z\^_`a-z\|~]+) */g
79 var textRegExp = /^[\x20-\x7e\x80-\xff]+$/
80 var tokenRegExp = /^[!#$%&'\*\+\-\.0-9A-Z\^_`a-z\|~]+$/
83 * RegExp for various RFC 5987 grammar
85 * ext-value = charset "'" [ language ] "'" value-chars
86 * charset = "UTF-8" / "ISO-8859-1" / mime-charset
87 * mime-charset = 1*mime-charsetc
88 * mime-charsetc = ALPHA / DIGIT
89 * / "!" / "#" / "$" / "%" / "&"
90 * / "+" / "-" / "^" / "_" / "`"
92 * language = ( 2*3ALPHA [ extlang ] )
95 * extlang = *3( "-" 3ALPHA )
96 * value-chars = *( pct-encoded / attr-char )
97 * pct-encoded = "%" HEXDIG HEXDIG
98 * attr-char = ALPHA / DIGIT
99 * / "!" / "#" / "$" / "&" / "+" / "-" / "."
100 * / "^" / "_" / "`" / "|" / "~"
103 var extValueRegExp = /^([A-Za-z0-9!#$%&+\-^_`{}~]+)'(?:[A-Za-z]{2,3}(?:-[A-Za-z]{3}){0,3}|[A-Za-z]{4,8}|)'((?:%[0-9A-Fa-f]{2}|[A-Za-z0-9!#$&+\-\.^_`|~])+)$/
106 * RegExp for various RFC 6266 grammar
108 * disposition-type = "inline" | "attachment" | disp-ext-type
109 * disp-ext-type = token
110 * disposition-parm = filename-parm | disp-ext-parm
111 * filename-parm = "filename" "=" value
112 * | "filename*" "=" ext-value
113 * disp-ext-parm = token "=" value
114 * | ext-token "=" ext-value
115 * ext-token = <the characters in token, followed by "*">
118 var dispositionTypeRegExp = /^([!#$%&'\*\+\-\.0-9A-Z\^_`a-z\|~]+) *(?:$|;)/
121 * Create an attachment Content-Disposition header.
123 * @param {string} [filename]
124 * @param {object} [options]
125 * @param {string} [options.type=attachment]
126 * @param {string|boolean} [options.fallback=true]
131 function contentDisposition(filename, options) {
132 var opts = options || {}
135 var type = opts.type || 'attachment'
138 var params = createparams(filename, opts.fallback)
140 // format into string
141 return format(new ContentDisposition(type, params))
145 * Create parameters object from filename and fallback.
147 * @param {string} [filename]
148 * @param {string|boolean} [fallback=true]
153 function createparams(filename, fallback) {
154 if (filename === undefined) {
160 if (typeof filename !== 'string') {
161 throw new TypeError('filename must be a string')
164 // fallback defaults to true
165 if (fallback === undefined) {
169 if (typeof fallback !== 'string' && typeof fallback !== 'boolean') {
170 throw new TypeError('fallback must be a string or boolean')
173 if (typeof fallback === 'string' && nonLatin1RegExp.test(fallback)) {
174 throw new TypeError('fallback must be ISO-8859-1 string')
177 // restrict to file base name
178 var name = basename(filename)
180 // determine if name is suitable for quoted string
181 var isQuotedString = textRegExp.test(name)
183 // generate fallback name
184 var fallbackName = typeof fallback !== 'string'
185 ? fallback && getlatin1(name)
187 var hasFallback = typeof fallbackName === 'string' && fallbackName !== name
189 // set extended filename parameter
190 if (hasFallback || !isQuotedString || hexEscapeRegExp.test(name)) {
191 params['filename*'] = name
194 // set filename parameter
195 if (isQuotedString || hasFallback) {
196 params.filename = hasFallback
205 * Format object to Content-Disposition header.
207 * @param {object} obj
208 * @param {string} obj.type
209 * @param {object} [obj.parameters]
214 function format(obj) {
215 var parameters = obj.parameters
218 if (!type || typeof type !== 'string' || !tokenRegExp.test(type)) {
219 throw new TypeError('invalid type')
222 // start with normalized type
223 var string = String(type).toLowerCase()
226 if (parameters && typeof parameters === 'object') {
228 var params = Object.keys(parameters).sort()
230 for (var i = 0; i < params.length; i++) {
233 var val = param.substr(-1) === '*'
234 ? ustring(parameters[param])
235 : qstring(parameters[param])
237 string += '; ' + param + '=' + val
245 * Decode a RFC 6987 field value (gracefully).
247 * @param {string} str
252 function decodefield(str) {
253 var match = extValueRegExp.exec(str)
256 throw new TypeError('invalid extended field value')
259 var charset = match[1].toLowerCase()
260 var encoded = match[2]
264 var binary = encoded.replace(hexEscapeReplaceRegExp, pdecode)
268 value = getlatin1(binary)
271 value = new Buffer(binary, 'binary').toString('utf8')
274 throw new TypeError('unsupported charset in extended field')
281 * Get ISO-8859-1 version of string.
283 * @param {string} val
288 function getlatin1(val) {
289 // simple Unicode -> ISO-8859-1 transformation
290 return String(val).replace(nonLatin1RegExp, '?')
294 * Parse Content-Disposition header string.
296 * @param {string} string
301 function parse(string) {
302 if (!string || typeof string !== 'string') {
303 throw new TypeError('argument string is required')
306 var match = dispositionTypeRegExp.exec(string)
309 throw new TypeError('invalid type format')
313 var index = match[0].length
314 var type = match[1].toLowerCase()
321 // calculate index to start at
322 index = paramRegExp.lastIndex = match[0].substr(-1) === ';'
327 while (match = paramRegExp.exec(string)) {
328 if (match.index !== index) {
329 throw new TypeError('invalid parameter format')
332 index += match[0].length
333 key = match[1].toLowerCase()
336 if (names.indexOf(key) !== -1) {
337 throw new TypeError('invalid duplicate parameter')
342 if (key.indexOf('*') + 1 === key.length) {
343 // decode extended value
344 key = key.slice(0, -1)
345 value = decodefield(value)
347 // overwrite existing value
352 if (typeof params[key] === 'string') {
356 if (value[0] === '"') {
357 // remove quotes and escapes
359 .substr(1, value.length - 2)
360 .replace(qescRegExp, '$1')
366 if (index !== -1 && index !== string.length) {
367 throw new TypeError('invalid parameter format')
370 return new ContentDisposition(type, params)
374 * Percent decode a single character.
376 * @param {string} str
377 * @param {string} hex
382 function pdecode(str, hex) {
383 return String.fromCharCode(parseInt(hex, 16))
387 * Percent encode a single character.
389 * @param {string} char
394 function pencode(char) {
395 var hex = String(char)
399 return hex.length === 1
405 * Quote a string for HTTP.
407 * @param {string} val
412 function qstring(val) {
413 var str = String(val)
415 return '"' + str.replace(quoteRegExp, '\\$1') + '"'
419 * Encode a Unicode string for HTTP (RFC 5987).
421 * @param {string} val
426 function ustring(val) {
427 var str = String(val)
429 // percent encode as UTF-8
430 var encoded = encodeURIComponent(str)
431 .replace(encodeUriAttrCharRegExp, pencode)
433 return 'UTF-8\'\'' + encoded
437 * Class for parsed Content-Disposition header for v8 optimization
440 function ContentDisposition(type, parameters) {
442 this.parameters = parameters