Added route-middleware example

docs/guide.md

@@ -155,7 +155,7 @@ may consume:
 
 We may pass control to the next _matching_ route, by calling the _third_ argument,
 the _next()_ function. When a match cannot be made, control is passed back to Connect,
-and middleware continue to be invoked.
+and middleware continue to be invoked. The same is true for several routes which have the same path defined, they will simply be executed in order until one does _not_ call _next()_.
 
 	app.get('/users/:id?', function(req, res, next){
 		var id = req.params.id;
@@ -170,6 +170,10 @@ and middleware continue to be invoked.
 		// do something else
 	});
 
+### Route Middleware
+
+Routes may utilize route-specific middleware by passing one or more additional callbacks (or arrays) to the method. This feature is extremely useful for restricting access, loading data used by the route etc.
+
 ### HTTP Methods
 
 We have seen _app.get()_ a few times, however Express also exposes other familiar HTTP verbs in the same manor, such as _app.post()_, _app.del()_, etc.

examples/route-middleware/app.js

@@ -0,0 +1,86 @@
+
+/**
+ * Module dependencies.
+ */
+
+var express = require('../../lib/express');
+
+var app = express.createServer();
+
+// Example requests:
+//     curl http://localhost:3000/user/0
+//     curl http://localhost:3000/user/0/edit
+//     curl http://localhost:3000/user/1
+//     curl http://localhost:3000/user/1/edit (unauthorized since this is not you)
+//     curl -X DELETE http://localhost:3000/user/0 (unauthorized since you are not an admin)
+
+// Dummy users
+var users = [
+    { id: 0, name: 'tj', email: 'tj@vision-media.ca', role: 'member' },
+    { id: 1, name: 'ciaran', email: 'ciaranj@gmail.com', role: 'member' },
+    { id: 2, name: 'aaron', email: 'aaron.heckmann+github@gmail.com', role: 'admin' }
+];
+
+function loadUser(req, res, next) {
+    // You would fetch your user from the db
+    var user = users[req.params.id];
+    if (user) {
+        req.user = user;
+        next();
+    } else {
+        next(new Error('Failed to load user ' + req.params.id));
+    }
+}
+
+function andRestrictToSelf(req, res, next) {
+    // If our authenticated user is the user we are viewing
+    // then everything is fine :)
+    if (req.authenticatedUser.id == req.user.id) {
+        next();
+    } else {
+        // You may want to implement specific exceptions
+        // such as UnauthorizedError or similar so that you
+        // can handle these in app.error() specifically
+        // (view ./examples/pages for this)
+        next(new Error('Unauthorized'));
+    }
+}
+
+function andRestrictTo(role) {
+    return function(req, res, next) {
+        if (req.authenticatedUser.role == role) {
+            next();
+        } else {
+            next(new Error('Unauthorized'));
+        }
+    }
+}
+
+// Middleware for faux authentication
+// you would of course implement something real,
+// but this illustrates how an authenticated user
+// may interacte with middleware
+
+app.use(function(req, res, next){
+    req.authenticatedUser = users[0];
+    next();
+});
+
+app.get('/', function(req, res){
+    res.redirect('/user/0');
+});
+
+app.get('/user/:id', loadUser, function(req, res){
+    res.send('Viewing user ' + req.user.name);
+});
+
+app.get('/user/:id/edit', loadUser, andRestrictToSelf, function(req, res){
+    res.send('Editing user ' + req.user.name);
+});
+
+app.del('/user/:id', loadUser, andRestrictTo('admin'), function(req, res){
+    res.send('Deleted user ' + req.user.name);
+});
+
+app.listen(3000);
+console.log('Express app started on port 3000');