winston-middleware 0.1.2 → 0.2.0

package/Readme.md

@@ -9,7 +9,7 @@
 
 ## Usage
 
-winston-middleware provides middlewares for request and error logging of your express.js application.
+winston-middleware provides middlewares for request and error logging of your express.js application.  It uses 'whitelists' to select properties from the request and (new in 0.2.x) response objects.
 
 ### Error Logging
 
@@ -17,7 +17,7 @@ Use `expressWinston.errorLogger(options)` to create a middleware that log the er
 
 ``` js
     app.use(app.router); // notice how the router goes first.
-    app.use(expressWinston.errorHandler({
+    app.use(expressWinston.errorLogger({
       transports: [
         new winston.transports.Console({
           json: true,
@@ -29,6 +29,13 @@ Use `expressWinston.errorLogger(options)` to create a middleware that log the er
 
 The logger needs to be added AFTER the express router(`app.router)`) and BEFORE any of your custom error handlers(`express.handler`). Since winston-middleware will just log the errors and not __handle__ them, you can still use your custom error handler like `express.handler`, just be sure to put the logger before any of your handlers.
 
+### Options
+
+``` js
+    transports: [<WinstonTransport>], // list of all winston transports instances to use.
+    level: String // log level to use, the default is "info".
+```
+
 ### Request Logging
 
 Use `expressWinston.logger(options)` to create a middleware to log your HTTP requests.
@@ -46,9 +53,9 @@ Use `expressWinston.logger(options)` to create a middleware to log your HTTP req
     app.use(app.router); // notice how the router goes after the logger.
 ```
 
-## Example
+## Examples
 
-``` js 
+``` js
     var express = require('express');
     var expressWinston = require('winston-middleware');
     var winston = require('winston'); // for transports.Console
@@ -69,8 +76,8 @@ Use `expressWinston.logger(options)` to create a middleware to log your HTTP req
 
     app.use(app.router);
 
-    // winston-middleware errorHandler makes sense AFTER the router.
-    app.use(expressWinston.errorHandler({
+    // winston-middleware errorLogger makes sense AFTER the router.
+    app.use(expressWinston.errorLogger({
       transports: [
         new winston.transports.Console({
           json: true,
@@ -80,7 +87,7 @@ Use `expressWinston.logger(options)` to create a middleware to log your HTTP req
     }));
 
     // Optionally you can include your custom error handler after the logging.
-    app.use(express.errorHandler({
+    app.use(express.errorLogger({
       dumpExceptions: true,
       showStack: true
     }));
@@ -120,9 +127,13 @@ Browse `/` to see a regular HTTP logging like this:
         "originalUrl": "/",
         "query": {}
       },
+      "res": {
+        "statusCode": 200
+      },
+      "responseTime" : 12,
       "level": "info",
       "message": "HTTP GET /favicon.ico"
-    } 
+    }
 
 Browse `/error` will show you how winston-middleware handles and logs the errors in the express pipeline like this:
 
@@ -199,23 +210,66 @@ Browse `/error` will show you how winston-middleware handles and logs the errors
       "message": "middlewareError"
     }
 
+## Whitelists
+New in version 0.2.x is the ability to add whitelist elements in a route.  winston-middleware adds a `_routeWhitelists` object to the `req`uest, containing `.body`, `.req` and .res` properties, to which you can set an array of 'whitelist' parameters to include in the log, specific to the route in question:
+
+``` js
+    app.post('/user/register', function(req, res, next) {
+      req._routeWhitelists.body = ['username', 'email', 'age']; // But not 'password' or 'confirm-password' or 'top-secret'
+      req._routeWhitelists.res = ['_headers'];
+    });
+```
+
+Post to `/user/register` would give you something like the following:
+
+    {
+      "req": {
+        "httpVersion": "1.1",
+        "headers": {
+          "host": "localhost:3000",
+          "connection": "keep-alive",
+          "accept": "*/*",
+          "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_4) AppleWebKit/536.11 (KHTML, like Gecko) Chrome/20.0.1132.57 Safari/536.11",
+          "accept-encoding": "gzip,deflate,sdch",
+          "accept-language": "en-US,en;q=0.8,es-419;q=0.6,es;q=0.4",
+          "accept-charset": "ISO-8859-1,utf-8;q=0.7,*;q=0.3",
+          "cookie": "connect.sid=nGspCCSzH1qxwNTWYAoexI23.seE%2B6Whmcwd"
+        },
+        "url": "/",
+        "method": "GET",
+        "originalUrl": "/",
+        "query": {},
+        "body": {
+          "username": "foo",
+          "email": "foo@bar.com",
+          "age": "72"
+        }
+      },
+      "res": {
+        "statusCode": 200
+      },
+      "responseTime" : 12,
+      "level": "info",
+      "message": "HTTP GET /favicon.ico"
+    }
+
 ## Tests
 
     npm test
 
 ## Issues and Collaboration
 
-* Add option to set the log level.
-* Add support for filtering of __req.body__. At this moment `body` is not included in the logging because it can contain sensitive fields like 'password' or 'password_confirmation'.
 * Implement a chain of requestFilters. Currently only one requestFilter is allowed in the options.
 
-We are accepting pull-request for this features.
+We are accepting pull-request for these features.
 
 If you ran into any problems, please use the project [Issues section](https://github.com/firebaseco/winston-middleware/issues) to search or post any bug.
 
 ## Contributors
 
-* Johan (author). Email: *johan@firebase.co*
+* [Johan Hernandez](https://github.com/thepumpkin1979) (https://github.com/thepumpkin1979)
+* [Lars Jacob](https://github.com/jaclar) (https://github.com/jaclar)
+* [Jonathan Lomas](https://github.com/floatingLomas) (https://github.com/floatingLomas)
 
 ## MIT License
 

package/index.js

@@ -1,15 +1,15 @@
 // Copyright (c) 2012 Firebase.co and Contributors - http://www.firebase.co
-// 
+//
 // 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 NON-INFRINGEMENT. IN NO EVENT SHALL THE
@@ -18,88 +18,171 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 // THE SOFTWARE.
 //
-
 var winston = require('winston');
-var async = require('async');
 var util = require('util');
 
-// default list of properties in the request object that are allowed to be logged.
-// these properties will be safely included in the meta of the log.
-// 'body' is not included in this list because it can contains passwords and stuff that are sensitive for logging.
-// TODO: Include 'body' and get the defaultRequestFilter to filter the inner properties like 'password' or 'password_confirmation', etc. Pull requests anyone?
+/**
+ * A default list of properties in the request object that are allowed to be logged.
+ * These properties will be safely included in the meta of the log.
+ * 'body' is not included in this list because it can contains passwords and stuff that are sensitive for logging.
+ * TODO: Include 'body' and get the defaultRequestFilter to filter the inner properties like 'password' or 'password_confirmation', etc. Pull requests anyone?
+ * @type {Array}
+ */
 var requestWhitelist = ['url', 'headers', 'method', 'httpVersion', 'originalUrl', 'query'];
 
-// default function to filter the properties of the req object.
-var defaultRequestFilter = function(req, propName) {
-  return req[propName];
+/**
+ * A default list of properties in the request body that are allowed to be logged.
+ * This will normally be empty here, since it should be done at the route level.
+ * @type {Array}
+ */
+var bodyWhitelist = [];
+
+/**
+ * A default list of properties in the response object that are allowed to be logged.
+ * These properties will be safely included in the meta of the log.
+ * @type {Array}
+ */
+var responseWhitelist = ['statusCode'];
+
+/**
+ * A default function to filter the properties of the req object.
+ * @param req
+ * @param propName
+ * @return {*}
+ */
+var defaultRequestFilter = function (req, propName) {
+    return req[propName];
 };
 
-function filterRequest(originalReq, initialFilter) {
-  var req = {};
-  Object.keys(originalReq).forEach(function(propName) {
-    // if the property is not in the whitelist, we return undefined so is not logged as part of the meta.
-    if(requestWhitelist.indexOf(propName) == -1) return;
-    var value = initialFilter(originalReq, propName);
-    if(typeof(value) !== 'undefined') {
-      req[propName] = value;
-    }
-  });
-  return req;
+/**
+ * A default function to filter the properties of the res object.
+ * @param res
+ * @param propName
+ * @return {*}
+ */
+var defaultResponseFilter = function (req, propName) {
+    return req[propName];
 };
 
-// 
+function filterObject(originalObj, whiteList, initialFilter) {
+
+    var obj = {};
+
+    [].concat(whiteList).forEach(function (propName) {
+        var value = initialFilter(originalObj, propName);
+
+        if(typeof (value) !== 'undefined') {
+            obj[propName] = value;
+        };
+    });
+
+    return obj;
+}
+
+//
 // ### function errorLogger(options)
 // #### @options {Object} options to initialize the middleware.
 //
+
+
 function errorLogger(options) {
-  if(!options) throw new Error("options are required by winston-middleware middleware");
-  if(!options.transports || !(options.transports.length > 0)) throw new Error("transports are required by winston-middleware middleware");
-  options.requestFilter = options.requestFilter || defaultRequestFilter;
-  return function(err, req, res, next) {
-    // let winston gather all the error data.
-    var exceptionMeta = winston.exception.getAllInfo(err);
-    exceptionMeta.req = filterRequest(req, options.requestFilter);
-
-    function logOnTransport(transport, nextTransport) {
-      return transport.logException('middlewareError', exceptionMeta, nextTransport);
-    };
 
-    function done() {
-      return next(err);
+    ensureValidOptions(options);
+
+    options.requestFilter = options.requestFilter || defaultRequestFilter;
+
+    return function (err, req, res, next) {
+
+        // Let winston gather all the error data.
+        var exceptionMeta = winston.exception.getAllInfo(err);
+        exceptionMeta.req = filterObject(req, requestWhitelist, options.requestFilter);
+
+        // This is fire and forget, we don't want logging to hold up the request so don't wait for the callback
+        for(var i = 0; i < options.transports.length; i++) {
+            var transport = options.transports[i];
+            transport.logException('middlewareError', exceptionMeta, function () {
+                // Nothing to do here
+            });
+        }
+
+        next(err);
     };
-    // iterate all the transports
-    async.forEach(options.transports, logOnTransport, done);
-  };
-};
+}
 
-// 
+//
 // ### function logger(options)
 // #### @options {Object} options to initialize the middleware.
 //
+
+
 function logger(options) {
-  if(!options) throw new Error("options are required by winston-middleware middleware");
-  if(!options.transports || !(options.transports.length > 0)) throw new Error("transports are required by winston-middleware middleware");
-  options.requestFilter = options.requestFilter || defaultRequestFilter;
-  options.level = options.level || "info";
-  return function(req, res, next) {
-    var meta = {
-      req: filterRequest(req, options.requestFilter)
-    };
-    var msg = util.format("HTTP %s %s", req.method, req.url);
 
-    function logOnTransport(transport, nextTransport) {
-      return transport.log(options.level, msg, meta, nextTransport);
-    };
+    ensureValidOptions(options);
+
+    options.requestFilter = options.requestFilter || defaultRequestFilter;
+    options.responseFilter = options.responseFilter || defaultResponseFilter;
+    options.level = options.level || "info";
+
+    return function (req, res, next) {
+
+        req._startTime = (new Date);
+
+        req._routeWhitelists = {
+            req: [],
+            res: [],
+            body: []
+        };
+
+        // Manage to get information from the response too, just like Connect.logger does:
+        var end = res.end;
+        res.end = function(chunk, encoding) {
+            var responseTime = (new Date) - req._startTime;
+
+            res.end = end;
+            res.end(chunk, encoding);
 
-    function done() {
-      return next();
+            var meta = {};
+
+            var bodyWhitelist;
+
+            requestWhitelist = requestWhitelist.concat(req._routeWhitelists.req || []);
+            responseWhitelist = responseWhitelist.concat(req._routeWhitelists.res || []);
+
+            meta.req = filterObject(req, requestWhitelist, options.requestFilter);
+            meta.res = filterObject(res, responseWhitelist, options.responseFilter);
+
+            bodyWhitelist = req._routeWhitelists.body || [];
+
+            if (bodyWhitelist) {
+                meta.req.body = filterObject(req.body, bodyWhitelist, options.requestFilter);
+            };
+
+            meta.responseTime = responseTime;
+
+            var msg = util.format("HTTP %s %s", req.method, req.url);
+
+            // This is fire and forget, we don't want logging to hold up the request so don't wait for the callback
+            for(var i = 0; i < options.transports.length; i++) {
+                var transport = options.transports[i];
+                transport.log(options.level, msg, meta, function () {
+                    // Nothing to do here
+                });
+            }
+        };
+
+        next();
     };
-    // iterate all the transports
-    async.forEach(options.transports, logOnTransport, done);
-  };
+}
+
+function ensureValidOptions(options) {
+    if(!options) throw new Error("options are required by winston-middleware middleware");
+    if(!options.transports || !(options.transports.length > 0)) throw new Error("transports are required by winston-middleware middleware");
 };
 
 module.exports.errorLogger = errorLogger;
 module.exports.logger = logger;
 module.exports.requestWhitelist = requestWhitelist;
+module.exports.bodyWhitelist = bodyWhitelist;
+module.exports.responseWhitelist = responseWhitelist;
 module.exports.defaultRequestFilter = defaultRequestFilter;
+module.exports.defaultResponseFilter = defaultResponseFilter;

package/package.json

@@ -3,7 +3,7 @@
   "name": "winston-middleware",
   "description": "express.js middleware for flatiron/winston",
   "keywords": ["winston", "flatiron", "logging", "express", "log", "error", "handler", "middleware"],
-  "version": "0.1.2",
+  "version": "0.2.0",
   "repository": {
     "url": "https://github.com/firebaseco/winston-middleware.git"
   },
@@ -12,8 +12,7 @@
     "test": "node test/test.js"
   },
   "dependencies": {
-    "winston": "0.6.x",
-    "async": "0.1.x"
+    "winston": "0.6.x"
   },
   "devDependencies": {
     "vows": "0.6.x"
@@ -23,7 +22,7 @@
   },
 	"licenses" : [
 		{
-			"type" : "MIT", 
+			"type" : "MIT",
 			"url" : "https://github.com/firebaseco/winston-middleware/blob/master/LICENSE"
 		}
 	]

package/test/test.js

@@ -15,12 +15,21 @@ vows.describe("exports").addBatch({
     topic: function() {
       return expressWinston;
     },
-    "an array with all the properties whilelist in the req object": function(exports) {
+    "an array with all the properties whitelisted in the req object": function(exports) {
       assert.isArray(exports.requestWhitelist);
     },
+    "an array with all the properties whitelisted in the res object": function(exports) {
+      assert.isArray(exports.responseWhitelist);
+    },
+    "an array with all the properties whitelisted in the body object": function(exports) {
+      assert.isArray(exports.bodyWhitelist);
+    },
     "and the factory should contain a default request filter function": function(exports) {
       assert.isFunction(exports.defaultRequestFilter);
     },
+    "and the factory should contain a default response filter function": function(exports) {
+      assert.isFunction(exports.defaultResponseFilter);
+    },
     "it should export a function for the creation of error loggers middlewares": function(exports) {
       assert.isFunction(exports.errorLogger);
     },
@@ -61,7 +70,7 @@ vows.describe("errorLogger").addBatch({
         var middleware = factory({
           transports: [
             new MockTransport({
-              
+
             })
           ]
         });
@@ -86,7 +95,7 @@ vows.describe("errorLogger").addBatch({
         params: {
           id: 20
         },
-        filteredProperty: "value that should not be logged"
+        nonWhitelistedProperty: "value that should not be logged"
       };
       var res = {
 
@@ -134,7 +143,7 @@ vows.describe("errorLogger").addBatch({
       assert.deepEqual(result.log.meta.req.query, {
                       val: '1'
       });
-      assert.isUndefined(result.log.meta.req.filteredProperty);
+      assert.isUndefined(result.log.meta.req.nonWhitelistedProperty);
     },
     "the winston-middleware middleware should not swallow the pipeline error": function(result) {
       assert.isNotNull(result.pipelineError);
@@ -143,7 +152,7 @@ vows.describe("errorLogger").addBatch({
   }
 }).export(module);
 
-vows.describe("logger").addBatch({
+vows.describe("logger 0.1.x").addBatch({
   "when I run the middleware factory": {
     topic: function() {
       return expressWinston.logger;
@@ -174,7 +183,7 @@ vows.describe("logger").addBatch({
         var middleware = factory({
           transports: [
             new MockTransport({
-              
+
             })
           ]
         });
@@ -202,14 +211,15 @@ vows.describe("logger").addBatch({
         filteredProperty: "value that should not be logged"
       };
       var res = {
-
+        end: function(chunk, encoding) {}
       };
       var test = {
         req: req,
         res: res,
         log: {}
       };
-      var next = function() {
+      var next = function(_req, _res, next) {
+        res.end();
         return callback(null, test);
       };
 
@@ -241,3 +251,134 @@ vows.describe("logger").addBatch({
     }
   }
 }).export(module);
+
+vows.describe("logger 0.2.x").addBatch({
+  "when I run the middleware factory": {
+    topic: function() {
+      return expressWinston.logger;
+    },
+    "without options": {
+      "an error should be raised": function(factory) {
+        assert.throws(function() {
+          factory();
+        }, Error);
+      }
+    },
+    "without any transport specified": {
+      "an error should be raised": function(factory) {
+        assert.throws(function() {
+          factory({});
+        }, Error);
+      }
+    },
+    "with an empty list of transports": {
+      "an error should be raised": function(factory) {
+        assert.throws(function() {
+          factory({transports:[]});
+        }, Error);
+      }
+    },
+    "with proper options": {
+      "the result should be a function with three arguments that fit req, res, next": function (factory) {
+        var middleware = factory({
+          transports: [
+            new MockTransport({
+
+            })
+          ]
+        });
+        assert.equal(middleware.length, 3);
+      }
+    }
+  },
+  "When the winston-middleware middleware is invoked in pipeline": {
+    topic: function() {
+      var factory = expressWinston.logger;
+      var callback = this.callback;
+      var req = {
+        url: "/hello?val=1",
+        headers: {
+          'header-1': 'value 1'
+        },
+        method: 'GET',
+        query: {
+          val: '2'
+        },
+        originalUrl: "/hello?val=2",
+        params: {
+          id: 20
+        },
+        nonWhitelistedProperty: "value that should not be logged",
+        routeLevelAddedProperty: "value that should be logged",
+        body: {
+          username: 'bobby',
+          password: 'top-secret'
+        }
+      };
+      var res = {
+        statusCode: 200,
+        nonWhitelistedProperty: "value that should not be logged",
+        routeLevelAddedProperty: "value that should be logged",
+        end: function(chunk, encoding) {
+
+        }
+      };
+      var test = {
+        req: req,
+        res: res,
+        log: {}
+      };
+      var next = function(_req, _res, next) {
+        req._startTime = (new Date) - 125;
+
+        req._routeWhitelists.req = [ 'routeLevelAddedProperty' ];
+        req._routeWhitelists.body = [ 'username' ];
+
+        res.end();
+        return callback(null, test);
+      };
+
+      var transport = new MockTransport({});
+      transport.log = function(level, msg, meta, cb) {
+        test.transportInvoked = true;
+        test.log.level = level;
+        test.log.msg = msg;
+        test.log.meta = meta;
+        this.emit('logged');
+        return cb();
+      };
+      var middleware = factory({
+        transports: [transport]
+      });
+      middleware(req, res, next);
+    }
+    , "then the transport should be invoked": function(result){
+      assert.isTrue(result.transportInvoked);
+    }
+    , "the meta should contain a filtered request": function(result){
+      assert.isTrue(!!result.log.meta.req, "req should be defined in meta");
+      assert.isNotNull(result.log.meta.req);
+      assert.equal(result.log.meta.req.method, "GET");
+      assert.deepEqual(result.log.meta.req.query, { val: '2' });
+      assert.isUndefined(result.log.meta.req.nonWhitelistedProperty);
+
+      assert.isNotNull(result.log.meta.req.routeLevelAddedProperty);
+    }
+    , "the meta should contain a filtered request body": function(result) {
+      assert.deepEqual(result.log.meta.req.body, {username: 'bobby'});
+      assert.isUndefined(result.log.meta.req.body.password);
+    }
+    , "the meta should contain a filtered response": function(result){
+      assert.isTrue(!!result.log.meta.res, "res should be defined in meta");
+      assert.isNotNull(result.log.meta.res);
+      assert.equal(result.log.meta.res.statusCode, 200);
+      assert.isNotNull(result.log.meta.res.routeLevelAddedProperty);
+    }
+    , "the meta should contain a response time": function(result){
+      assert.isTrue(!!result.log.meta.responseTime, "responseTime should be defined in meta");
+      assert.isNotNull(result.log.meta.responseTime);
+      assert.isTrue(result.log.meta.responseTime > 120);
+      assert.isTrue(result.log.meta.responseTime < 130);
+    }
+  }
+}).export(module);