Sweet Disposition: Interoperable Content-Disposistion headers for Node.JS
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
lib Check for path separators, percent characters Jul 14, 2011


Sweet: Setting HTTP Content-Disposition Headers

Getting the syntax for HTTP Content-Disposition headers to work well with browsers well is tricky, especially if you want the filename to contain non-ASCII characters.

Sweet is here to help.

It exposes one function - make_disposition ( disposition, filename, fallback )- that takes the disposition ("attachment" or "inline"), a filename (possibly non-ASCII) and a fallback filename (always ASCII). and returns a value suitable for use as a Content-Disposition header value.

For example:

var http = require('http');
var sweet = require('sweet');

// "my stuff" in Japanese
var cd_value = sweet.make_disposition(
  'attachment', '私のもの', 'my stuff'

http.createServer(function (req, res) {
  res.writeHead(200, {
    'Content-Type': 'text/plain',
    'Content-Disposition': cd_value
  res.end('Hello World\n');
}).listen(1337, "");

See RFC6266 for the spec and related details.

Note that Sweet is just for setting Content-Disposition in HTTP responses (e.g., for file downloads); it won't help with MIME multi-part messages, for example.

Frequently Asked Questions

Why shouldn't I just produce the C-D header in UTF-8 directly?

HTTP headers are defined to be ISO-8859-1, so encoding them as UTF-8 assumes that the client will correctly "sniff" the encoding.

Unfortunately, there are some UTF-8 characters that look like ISO-8859-1 characters, such as an a with an umlaut (ä). In these cases, some browsers will treat it as UTF-8, even though it's valid ISO-8859-1, causing a loss of interoperability; your users will see the wrong filename.

How will browsers treat Sweet's Content-Disposition headers?

If you're generating non-ASCII filenames, all current releases of mainstream browsers will see it, except for Safari (which falls back to the ASCII filename).

Internet Explorer versions 6, 7 and 8, as well as Mozilla 3, 3.5 and 4 will also use the ASCII filename.

See the browser tests for more detail.


Mark Nottingham mnot@mnot.net