https://github.com/one-com/express-negotiator
Express/connect middleware that does HTTP content negotiation for static files
https://github.com/one-com/express-negotiator
Last synced: about 1 month ago
JSON representation
Express/connect middleware that does HTTP content negotiation for static files
- Host: GitHub
- URL: https://github.com/one-com/express-negotiator
- Owner: One-com
- License: bsd-3-clause
- Created: 2012-11-04T21:24:14.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2024-01-16T10:25:16.000Z (over 1 year ago)
- Last Synced: 2025-03-28T00:45:06.066Z (about 2 months ago)
- Language: JavaScript
- Size: 99.6 KB
- Stars: 4
- Watchers: 14
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
express-negotiator
==================
Express/connect middleware for doing content negotiation with static
files on disc. Heavily inspired by Apache's mod_negotiation.
Negotiator rewrites `req.url` to the negotiated file name based on
these factors (in descending order of importance):
* Whether `req.url` matches a file name on disc exactly
* The `locale` GET parameter
* The value of a locale cookie (optional, specified by `options.cookieName`)
* The `Accept-Language` and `Accept` headers
... and of course the availability of suitable files on disc. If no
acceptable match is found, `req.url` is left untouched.
Like `mod_negotiation`, `express-negotiator` interprets the extensions
of the files on disc as an unordered set. A file called `foo.html.fr`
would be treated the same as one called `foo.fr.html` except when the
request url specifies an exact match.
The negotiator middleware is intended to run right before `static`
pointed at the same directory as `options.root`.
If `options.cookieName` is specified, the `cookieParser` middleware
must also be in the middleware chain.
Conditional requests
====================
When the url is rewritten, negotiator sets the ETag header to the same
value as the `static` middleware would
(`"-"`), but with the negotiated Content-Type
and locale id bits suffixed. This prevents false positive 304
responses with `If-None-Match` when the same client (or reverse proxy)
requests the same url later with different headers (eg. after a locale
cookie change). That would happen if the files happened to have the
same size and modification times.
Also, the `If-Modified-Since` header is removed since that would cause
the `static` middleware to reply `304 Not Modified` in similar
situations. ETags are a superior concept anyway.
Installation
============
Make sure you have node.js and npm installed, then run:
```
$ npm install express-negotiator
```
Example usage
=============
```javascript
var express = require('express'),
negotiator = require('express-negotiator'),
root = '/path/to/static/files',
app = express.createServer();
app
.use(express.cookieParser())
.use(negotiator({root: root, cookieName: 'mycookie'}))
.use(express.static(root))
.listen(1337);
```
If the root dir contains the files `index.en.html`, `index.da.html`,
and `foo.png` these example requests would be rewritten as follows:
```
GET / HTTP/1.1
Accept: text/html
Accept-Language: en
=> /index.en.html
Response ETag: "--text/html-en"
```
```
GET /?locale=da HTTP/1.1
Accept: text/html
Accept-Language: en
=> /index.da.html
Response ETag: "--text/html-da"
```
```
GET /index HTTP/1.1
Cookie: mycookie=da
Accept: text/html
Accept-Language: en
=> /index.da.html
Response ETag: "--text/html-da"
```
```
GET /foo HTTP/1.1
Accept: image/*
=> /foo.png
Response ETag: "--image/png"
```
See the test suite for more examples.
License
=======
express-negotiator is licensed under a standard 3-clause BSD license
-- see the `LICENSE` file for details.