Project import

cleishm · Dec 7, 2011 · 14af3df · 14af3df
commit 14af3df
Show file tree

Hide file tree

Showing 9 changed files with 392 additions and 0 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,3 @@
+.DS_Store
+node_modules
+*.sock
diff --git a/.npmignore b/.npmignore
@@ -0,0 +1,4 @@
+support
+test
+examples
+*.sock
diff --git a/History.md b/History.md
@@ -0,0 +1,5 @@
+
+0.0.1 / 2011-12-07
+==================
+
+  * Initial release
diff --git a/Makefile b/Makefile
@@ -0,0 +1,6 @@
+
+test:
+	@NODE_ENV=test ./node_modules/.bin/expresso \
+	  --require should
+
+.PHONY: test
diff --git a/Readme.md b/Readme.md
@@ -0,0 +1,108 @@
+
+# express-negotiate
+
+  Express content negotiation functions.
+
+## Installation
+
+    $ npm install express-negotiate
+
+## Usage
+
+Require the module to add the request.negotiate method:
+
+```javascript
+var express = require('express')
+    , negotiate = require('express-negotiate');
+```
+
+Then use in the route handler:
+
+```javascript
+app.get('/index', function(req, res, next) {
+    req.negotiate({
+        'application/json': function() {
+            res.send('{ message: 'Hello World' }');
+        },
+        'html': function() {
+            res.send('<html><body><h1>Hello World</h1></body></html>');
+        },
+        'default': function() {
+            // send HTML anyway
+            res.send('<html><body><h1>Hello World</h1></body></html>');
+        }
+    });
+});
+```
+
+## Handling unacceptable requests
+
+If a 'default' handler is not provided, then req.negotiate will throw
+a negotiate.NotAcceptable error.  This can be caught and handled using
+express error handling:
+
+```javascript
+app.get('/index', function(req, res, next) {
+    req.negotiate({
+        'application/json': function() {
+            res.send('{ message: 'Hello World' }');
+        }
+    });
+});
+
+app.error(function(err, req, res, next) {
+    if (err instanceof negotiate.NotAcceptable) {
+        res.send('Sorry, I dont know how to return any of the Content-Types requested', 406);
+    } else {
+        next(err);
+    }
+});
+```
+
+
+## Allowing route filename extensions to override Accept header
+
+By parsing out any filename extension on the route, and passing
+this to req.negotiate, the client can force a particular
+Content-Type regardless of the Accept header.
+
+```javascript
+app.get('/index.:format?', function(req, res, next) {
+    req.negotiate(req.params.format, {
+        'application/json': function() {
+            res.send('{ message: 'Hello World' }');
+        }
+    });
+});
+```
+
+
+## Credits
+
+Methods for parsing HTTP header qStrings taken from connect-conneg,
+by Jeff Craig (https://github.com/foxxtrot/connect-conneg).
+
+## License 
+
+(The MIT License)
+
+Copyright (c) 2011 Chris Leishman &lt;chris@leishman.org&gt;
+
+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.
diff --git a/index.js b/index.js
@@ -0,0 +1,2 @@
+
+module.exports = require('./lib/express-negotiate');
diff --git a/lib/express-negotiate.js b/lib/express-negotiate.js
@@ -0,0 +1,127 @@
+
+/*!
+ * express-negotiate
+ * Copyright(c) 2011 Chris Leishman <chris@leishman.org>
+ * MIT Licensed
+ */
+
+
+/**
+ * Library version.
+ */
+exports.version = '0.0.1';
+
+
+/**
+ * Module dependencies.
+ */
+var request = require('http').IncomingMessage.prototype
+    , mime = require('mime');
+var qStringRegex = /^\s*q=([01](?:\.\d+))\s*$/;
+
+
+/**
+ * NotAcceptable error type
+ *
+ * To catch and handle:
+ *   var negotiate = require('express-negotiate');
+ *
+ *   ...
+ *
+ *   app.error(function(err, req, res, next) {
+ *     if (err instanceof negotiate.NotAcceptable) {
+ *       res.send('Sorry, cant give you it in that format', 406);
+ *     } else {
+ *       next(err);
+ *     }
+ *   });
+ */
+function NotAcceptable(msg) {
+    this.name = 'NotAcceptable';
+    Error.call(this, msg);
+    Error.captureStackTrace(this, arguments.callee);
+}
+
+NotAcceptable.prototype.__proto__ = Error.prototype;
+
+exports.NotAcceptable = NotAcceptable;
+
+
+/**
+ * Add 'negotiate' method to request (http.IncomingMessage)
+ *
+ * @param {String} format
+ * @param {Object} content handlers
+ * @api public
+ */
+request.negotiate = function(format, handlers) {
+    var format;
+    if (arguments.length == 1) {
+        handlers = format;
+        format = undefined;
+    }
+    handlers = handlers || {};
+
+    var types;
+    if (typeof format !== 'undefined' && format !== '') {
+        types = [ lookup_type(format) ];
+    } else if (typeof this.headers['accepts'] !== 'undefined') {
+        types = sortQArrayString(this.headers['accepts']);
+    } else {
+        types = [];
+    }
+
+    for (var idx in types) {
+        var type = types[idx];
+        for (var handlerType in handlers) {
+            if (handlerType === 'default')
+                continue;
+            if (lookup_type(handlerType) === type)
+                return handlers[handlerType]();
+        }
+    }
+
+    if (handlers['default'])
+        return handlers['default']();
+    else
+        throw new NotAcceptable('No acceptable Content-Type handler or default handler found');
+};
+
+
+function lookup_type(type) {
+    if (type && !~type.indexOf('/'))
+        type = mime.lookup(type);
+    return type;
+}
+
+
+/*
+ * Methods below from https://github.com/foxxtrot/connect-conneg
+ */
+
+function parseQString(qString) {
+    var d = qStringRegex.exec(qString);
+    if (!d) {
+        return 1;
+    }
+    return Number(d[1]);
+}
+
+
+function sortQArrayString(content) {
+    var entries = content.split(','), sortData = [];
+    entries.forEach(function(rec) {
+        var s = rec.split(';');
+        sortData.push({
+            key: s[0],
+            quality: parseQString(s[1])
+        });
+    });
+
+    sortData.sort(function(a, b) {
+        if (a.quality > b.quality) { return -1; }
+        if (a.quality < b.quality) { return 1;  }
+        return 0;
+    });
+    return sortData.map(function(rec) { return rec.key.trim(); });
+}
diff --git a/package.json b/package.json
@@ -0,0 +1,21 @@
+{
+    "name": "express-negotiate"
+  , "version": "0.0.1"
+  , "description": "Express content negotiation functions"
+  , "keywords": ["express"]
+  , "author": "Chris Leishman <chris@leishman.org>"
+  , "dependencies": {
+      "mime": ">= 0.0.1"
+  }
+  , "devDependencies": {
+      "should": "0.2.1"
+    , "express": ">= 2.3.7"
+    , "expresso": ">= 0.7.6"
+  }
+  , "main": "index"
+  , "engines": { "node": ">= 0.2.0" }
+  , "repository": {
+      "type": "git"
+    , "url": "git://github.com/chrisleishman/express-negotiate.git"
+  }
+}