winston-middleware 0.2.4 → 1.0.0

package/.travis.yml

@@ -2,4 +2,11 @@ language: node_js
 node_js:
   - "0.6"
   - "0.8"
-script: "npm test"
+  - "0.10"
+  - "0.11"
+  - "0.12"
+  - "iojs"
+
+script:
+  - "test $TRAVIS_NODE_VERSION  = '0.6' || npm test"
+  - "test $TRAVIS_NODE_VERSION != '0.6' || npm run-script test-coverage"

package/AUTHORS

@@ -1,4 +1,7 @@
 Heapsource <npm@heapsource.com> (http://www.heapsource.com)
 Lars Jacob (http://jaclar.net)
-Jonathan Lomas (http://feedbackular.com)
+Jonathan Lomas (http://floatinglomas.ca)
 Xavier Damman (http://xdamman.com)
+Quentin Rossetti <quentin.rossetti@gmail.com>
+Damian Kaczmarek <rush@rushbase.net>
+Robbie Trencheny <me@robbiet.us> (http://robbie.io)

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2012-2013 Heapsource.com - http://www.heapsource.com
+Copyright (c) 2012-2014 Bithavoc.io - http://bithavoc.io
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/Readme.md

@@ -1,12 +1,18 @@
 # winston-middleware
-[![Build Status](https://secure.travis-ci.org/firebaseco/winston-middleware.png)](http://travis-ci.org/firebaseco/winston-middleware)
+[![Build Status](https://secure.travis-ci.org/bithavoc/winston-middleware.png)](http://travis-ci.org/bithavoc/winston-middleware)
 
 > [winston](https://github.com/flatiron/winston) middleware for express.js
 
 ## Installation
 
+Newcomers should start with the latest branch which makes use of winston 1.x.x:
+
     npm install winston-middleware
 
+If you're already using winston-middleware, and want to stick with the stable version based on winston 0.9.x, you should instead do:
+
+    npm install winston-middleware@0.3.x --save
+
 ## Usage
 
 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.
@@ -38,7 +44,9 @@ var winston = require('winston'),
 Use `expressWinston.errorLogger(options)` to create a middleware that log the errors of the pipeline.
 
 ``` js
-    app.use(app.router); // notice how the router goes first.
+    var router = require('./my-express-router');
+
+    app.use(router); // notice how the router goes first.
     app.use(expressWinston.errorLogger({
       transports: [
         new winston.transports.Console({
@@ -55,14 +63,22 @@ The logger needs to be added AFTER the express router(`app.router)`) and BEFORE
 
 ``` js
     transports: [<WinstonTransport>], // list of all winston transports instances to use.
-    level: String // log level to use, the default is "info".
+    winstonInstance: <WinstonLogger>, // a winston logger instance. If this is provided the transports option is ignored
+    level: String, // log level to use, the default is "info".
+    statusLevels: Boolean // different HTTP status codes caused log messages to be logged at different levels (info/warn/error), the default is false
+    skip: function(req, res) // function to determine if logging is skipped, defaults to false
 ```
 
+To use winston's existing transports, set `transports` to the values (as in key-value) of the `winston.default.transports` object. This may be done, for example, by using underscorejs: `transports: _.values(winston.default.transports)`.
+
+Alternatively, if you're using a winston logger instance elsewhere and have already set up levels and transports, pass the instance into expressWinston with the `winstonInstance` option. The `transports` option is then ignored.
+
 ### Request Logging
 
 Use `expressWinston.logger(options)` to create a middleware to log your HTTP requests.
 
 ``` js
+    var router = require('./my-express-router');
 
     app.use(expressWinston.logger({
       transports: [
@@ -72,9 +88,13 @@ Use `expressWinston.logger(options)` to create a middleware to log your HTTP req
         })
       ],
       meta: true, // optional: control whether you want to log the meta data about the request (default to true)
-      msg: "HTTP {{req.method}} {{req.url}}" // optional: customize the default logging message. E.g. "{{res.statusCode}} {{req.method}} {{res.responseTime}}ms {{req.url}}"
+      msg: "HTTP {{req.method}} {{req.url}}", // optional: customize the default logging message. E.g. "{{res.statusCode}} {{req.method}} {{res.responseTime}}ms {{req.url}}"
+      expressFormat: true, // Use the default Express/morgan request formatting, with the same colors. Enabling this will override any msg and colorStatus if true. Will only output colors on transports with colorize set to true
+      colorStatus: true, // Color the status code, using the Express/morgan color palette (default green, 3XX cyan, 4XX yellow, 5XX red). Will not be recognized if expressFormat is true
+      ignoreRoute: function (req, res) { return false; } // optional: allows to skip some log messages based on request and/or response
     }));
-    app.use(app.router); // notice how the router goes after the logger.
+
+    app.use(router); // notice how the router goes after the logger.
 ```
 
 ## Examples
@@ -88,6 +108,18 @@ Use `expressWinston.logger(options)` to create a middleware to log your HTTP req
     app.use(express.bodyParser());
     app.use(express.methodOverride());
 
+    // Let's make our express `Router` first.
+    var router = express.Router();
+    router.get('/error', function(req, res, next) {
+      // here we cause an error in the pipeline so we see winston-middleware in action.
+      return next(new Error("This is an error and it should be logged to the console"));
+    });
+
+    app.get('/', function(req, res, next) {
+      res.write('This is a normal request, it should be logged to the console too');
+      res.end();
+    });
+
     // winston-middleware logger makes sense BEFORE the router.
     app.use(expressWinston.logger({
       transports: [
@@ -98,7 +130,8 @@ Use `expressWinston.logger(options)` to create a middleware to log your HTTP req
       ]
     }));
 
-    app.use(app.router);
+    // Now we can tell the app to use our routing code:
+    app.use(router);
 
     // winston-middleware errorLogger makes sense AFTER the router.
     app.use(expressWinston.errorLogger({
@@ -116,18 +149,8 @@ Use `expressWinston.logger(options)` to create a middleware to log your HTTP req
       showStack: true
     }));
 
-    app.get('/error', function(req, res, next) {
-      // here we cause an error in the pipeline so we see winston-middleware in action.
-      return next(new Error("This is an error and it should be logged to the console"));
-    });
-
-    app.get('/', function(req, res, next) {
-      res.write('This is a normal request, it should be logged to the console too');
-      res.end();
-    });
-
     app.listen(3000, function(){
-      console.log("winston-middleware demo listening on port %d in %s mode", app.address().port, app.settings.env);
+      console.log("winston-middleware demo listening on port %d in %s mode", this.address().port, app.settings.env);
     });
 ```
 
@@ -234,11 +257,42 @@ Browse `/error` will show you how winston-middleware handles and logs the errors
       "message": "middlewareError"
     }
 
-## Whitelists
+## Global Whitelists and Blacklists
+
+winston-middleware exposes three whitelists that control which properties of the `request`, `body`, and `response` are logged:
+
+* `requestWhitelist`
+* `bodyWhitelist`, `bodyBlacklist`
+* `responseWhitelist`
+
+For example, `requestWhitelist` defaults to:
+
+    ['url', 'headers', 'method', 'httpVersion', 'originalUrl', 'query'];
+
+Only those properties of the request object will be logged. Set or modify the whitelist as necessary.
+
+For example, to include the session property (the session data), add the following during logger setup:
+
+    expressWinston.requestWhitelist.push('session');
+
+The blacklisting excludes certain properties and keeps all others. If both `bodyWhitelist` and `bodyBlacklist` are set
+the properties excluded by the blacklist are not included even if they are listed in the whitelist!
+
+Example:
+
+    expressWinston.bodyBlacklist.push('secretid', 'secretproperty');
+
+Note that you can log the whole request and/or response body:
+
+    expressWinston.requestWhitelist.push('body');
+    expressWinston.responseWhitelist.push('body');
+
+## Route-Specific Whitelists and Blacklists
+
 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) {
+    router.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'];
     });
@@ -277,21 +331,42 @@ Post to `/user/register` would give you something like the following:
       "message": "HTTP GET /favicon.ico"
     }
 
+Blacklisting supports only the `body` property.
+
+
+``` js
+    router.post('/user/register', function(req, res, next) {
+      req._routeWhitelists.body = ['username', 'email', 'age']; // But not 'password' or 'confirm-password' or 'top-secret'
+      req._routeBlacklists.body = ['username', 'password', 'confirm-password', 'top-secret'];
+      req._routeWhitelists.res = ['_headers'];
+    });
+```
+
+If both `req._bodyWhitelist.body` and `req._bodyBlacklist.body` are set the result will be the white listed properties
+excluding any black listed ones. In the above example, only 'email' and 'age' would be included.
+
+
 ## Tests
 
+Run the basic Mocha tests:
+
     npm test
 
-## Issues and Collaboration
+Run the Travis-CI tests (which will fail with < 100% coverage):
 
-* Implement a chain of requestFilters. Currently only one requestFilter is allowed in the options.
+    npm test-travis
 
-We are accepting pull-request for these features.
+Generate the `coverage.html` coverage report:
+
+    npm test-coverage
+
+## Issues and Collaboration
 
-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.
+If you ran into any problems, please use the project [Issues section](https://github.com/bithavoc/winston-middleware/issues) to search or post any bug.
 
 ## Contributors
 
-* [Johan Hernandez](https://github.com/thepumpkin1979) (https://github.com/thepumpkin1979)
+* [Johan Hernandez](https://github.com/bithavoc) (https://github.com/bithavoc)
 * [Lars Jacob](https://github.com/jaclar) (https://github.com/jaclar)
 * [Jonathan Lomas](https://github.com/floatingLomas) (https://github.com/floatingLomas)
 
@@ -299,7 +374,7 @@ Also see AUTHORS file, add yourself if you are missing.
 
 ## MIT License
 
-Copyright (c) 2012-2014 Heapsource.com and Contributors - http://www.heapsource.com
+Copyright (c) 2012-2014 Bithavoc.io and Contributors - http://bithavoc.io
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/index.js

@@ -20,6 +20,7 @@
 //
 var winston = require('winston');
 var util = require('util');
+var chalk = require('chalk');
 
 //Allow this file to get an exclusive copy of underscore so it can change the template settings without affecting others
 delete require.cache[require.resolve('underscore')];
@@ -42,6 +43,12 @@ var requestWhitelist = ['url', 'headers', 'method', 'httpVersion', 'originalUrl'
  */
 var bodyWhitelist = [];
 
+/**
+ * A default list of properties in the request body that are not allowed to be logged.
+ * @type {Array}
+ */
+var bodyBlacklist = [];
+
 /**
  * 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.
@@ -49,6 +56,13 @@ var bodyWhitelist = [];
  */
 var responseWhitelist = ['statusCode'];
 
+/**
+ * A list of request routes that will be skipped instead of being logged. This would be useful if routes for health checks or pings would otherwise pollute
+ * your log files.
+ * @type {Array}
+ */
+var ignoredRoutes = [];
+
 /**
  * A default function to filter the properties of the req object.
  * @param req
@@ -65,23 +79,33 @@ var defaultRequestFilter = function (req, propName) {
  * @param propName
  * @return {*}
  */
-var defaultResponseFilter = function (req, propName) {
-    return req[propName];
+var defaultResponseFilter = function (res, propName) {
+    return res[propName];
+};
+
+/**
+ * A default function to decide whether skip logging of particular request. Doesn't skip anything (i.e. log all requests).
+ * @return always false
+ */
+var defaultSkip = function() {
+  return false;
 };
 
 function filterObject(originalObj, whiteList, initialFilter) {
 
     var obj = {};
+    var fieldsSet = false;
 
     [].concat(whiteList).forEach(function (propName) {
         var value = initialFilter(originalObj, propName);
 
         if(typeof (value) !== 'undefined') {
             obj[propName] = value;
+            fieldsSet = true;
         };
     });
 
-    return obj;
+    return fieldsSet?obj:undefined;
 }
 
 //
@@ -95,6 +119,7 @@ function errorLogger(options) {
     ensureValidOptions(options);
 
     options.requestFilter = options.requestFilter || defaultRequestFilter;
+    options.winstonInstance = options.winstonInstance || (new winston.Logger ({ transports: options.transports }));
 
     return function (err, req, res, next) {
 
@@ -103,12 +128,7 @@ function errorLogger(options) {
         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
-            });
-        }
+        options.winstonInstance.log('error', 'middlewareError', exceptionMeta);
 
         next(err);
     };
@@ -123,13 +143,28 @@ function errorLogger(options) {
 function logger(options) {
 
     ensureValidOptions(options);
+    ensureValidLoggerOptions(options);
 
     options.requestFilter = options.requestFilter || defaultRequestFilter;
     options.responseFilter = options.responseFilter || defaultResponseFilter;
+    options.winstonInstance = options.winstonInstance || (new winston.Logger ({ transports: options.transports }));
     options.level = options.level || "info";
+    options.statusLevels = options.statusLevels || false;
     options.msg = options.msg || "HTTP {{req.method}} {{req.url}}";
+    options.colorStatus = options.colorStatus || false;
+    options.expressFormat = options.expressFormat || false;
+    options.ignoreRoute = options.ignoreRoute || function () { return false; };
+    options.skip = options.skip || defaultSkip;
+
+    // Using mustache style templating
+    var template = _.template(options.msg, null, {
+      interpolate: /\{\{(.+?)\}\}/g
+    });
 
     return function (req, res, next) {
+        var currentUrl = req.originalUrl || req.url;
+        if (currentUrl && _.contains(ignoredRoutes, currentUrl)) return next();
+        if (options.ignoreRoute(req, res)) return next();
 
         req._startTime = (new Date);
 
@@ -139,6 +174,10 @@ function logger(options) {
             body: []
         };
 
+        req._routeBlacklists = {
+            body: []
+        };
+
         // Manage to get information from the response too, just like Connect.logger does:
         var end = res.end;
         res.end = function(chunk, encoding) {
@@ -147,10 +186,27 @@ function logger(options) {
             res.end = end;
             res.end(chunk, encoding);
 
-            if(options.meta !== false) {
-              var meta = {};
+            req.url = req.originalUrl || req.url;
+
+            if (options.statusLevels) {
+              if (res.statusCode >= 100) { options.level = "info"; }
+              if (res.statusCode >= 400) { options.level = "warn"; }
+              if (res.statusCode >= 500) { options.level = "error"; }
+            };
+
+            if (options.colorStatus || options.expressFormat) {
+              // Palette from https://github.com/expressjs/morgan/blob/master/index.js#L205
+              var statusColor = 'green';
+              if (res.statusCode >= 500) statusColor = 'red';
+              else if (res.statusCode >= 400) statusColor = 'yellow';
+              else if (res.statusCode >= 300) statusColor = 'cyan';
+              var coloredStatusCode = chalk[statusColor](res.statusCode);
+            }
 
-              var bodyWhitelist;
+            var meta = {};
+
+            if(options.meta !== false) {
+              var bodyWhitelist, blacklist;
 
               requestWhitelist = requestWhitelist.concat(req._routeWhitelists.req || []);
               responseWhitelist = responseWhitelist.concat(req._routeWhitelists.res || []);
@@ -158,28 +214,44 @@ function logger(options) {
               meta.req = filterObject(req, requestWhitelist, options.requestFilter);
               meta.res = filterObject(res, responseWhitelist, options.responseFilter);
 
+              if (_.contains(responseWhitelist, 'body')) {
+                if (chunk) {
+                  var isJson = (res._headers && res._headers['content-type']
+                    && res._headers['content-type'].indexOf('json') >= 0);
+
+                  meta.res.body =  isJson ? JSON.parse(chunk) : chunk.toString();
+                }
+              }
+
               bodyWhitelist = req._routeWhitelists.body || [];
+              blacklist = _.union(bodyBlacklist, (req._routeBlacklists.body || []));
 
-              if (bodyWhitelist) {
-                  meta.req.body = filterObject(req.body, bodyWhitelist, options.requestFilter);
-              };
+              var filteredBody = null;
+
+              if ( req.body !== undefined ) {
+                  if (blacklist.length > 0 && bodyWhitelist.length === 0) {
+                    var whitelist = _.difference(_.keys(req.body), blacklist);
+                    filteredBody = filterObject(req.body, whitelist, options.requestFilter);
+                  } else {
+                    filteredBody = filterObject(req.body, bodyWhitelist, options.requestFilter);
+                  }
+              }
+              
+              if (filteredBody) meta.req.body = filteredBody;
 
               meta.responseTime = res.responseTime;
             }
 
-            // Using mustache style templating
-            _.templateSettings = {
-              interpolate: /\{\{(.+?)\}\}/g
-            };
-            var template = _.template(options.msg);
-            var msg = template({req: req, res: res});
-
+            if(options.expressFormat) {
+              var msg = chalk.grey(req.method + " " + req.url || req.url)
+                + " " + chalk[statusColor](res.statusCode)
+                + " " + chalk.grey(res.responseTime+"ms");
+            } else {
+              var msg = template({req: req, res: res});
+            }
             // 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
-                });
+            if (!options.skip(req, res)) {
+              options.winstonInstance.log(options.level, msg, meta);
             }
         };
 
@@ -189,13 +261,23 @@ function logger(options) {
 
 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");
-};
+    if(!((options.transports && (options.transports.length > 0)) || options.winstonInstance))
+        throw new Error("transports or a winstonInstance are required by winston-middleware middleware");
+}
+
+function ensureValidLoggerOptions(options) {
+    if (options.ignoreRoute && !_.isFunction(options.ignoreRoute)) {
+        throw new Error("`ignoreRoute` winston-middleware option should be a function");
+    }
+}
 
 module.exports.errorLogger = errorLogger;
 module.exports.logger = logger;
 module.exports.requestWhitelist = requestWhitelist;
 module.exports.bodyWhitelist = bodyWhitelist;
+module.exports.bodyBlacklist = bodyBlacklist;
 module.exports.responseWhitelist = responseWhitelist;
 module.exports.defaultRequestFilter = defaultRequestFilter;
 module.exports.defaultResponseFilter = defaultResponseFilter;
+module.exports.defaultSkip = defaultSkip;
+module.exports.ignoredRoutes = ignoredRoutes;

package/package.json

@@ -1,5 +1,9 @@
 {
-  "author": "Heapsource.com <npm@heapsource.com> (http://www.heapsource.com)",
+  "author": {
+    "name": "bithavoc",
+    "email": "im@bithavoc.io",
+    "url": "http://bithavoc.io"
+  },
   "name": "winston-middleware",
   "description": "express.js middleware for flatiron/winston",
   "keywords": [
@@ -10,25 +14,75 @@
     "log",
     "error",
     "handler",
-    "middleware"
+    "middleware",
+    "colors"
   ],
-  "version": "0.2.4",
+  "version": "1.0.0",
   "repository": {
-    "url": "https://github.com/heapsource/winston-middleware.git"
+    "type": "git",
+    "url": "https://github.com/bithavoc/winston-middleware.git"
+  },
+  "bugs": {
+    "url": "http://github.com/bithavoc/winston-middleware/issues",
+    "email": "im@bithavoc.io"
   },
   "main": "index.js",
   "scripts": {
-    "test": "vows --spec"
+    "test": "node_modules/.bin/mocha --reporter spec",
+    "test-travis": "node_modules/.bin/mocha --require blanket --reporter travis-cov",
+    "test-coverage": "node_modules/.bin/mocha --require blanket --reporter html-cov >| coverage.html || true"
+  },
+  "config": {
+    "travis-cov": {
+      "threshold": 100
+    },
+    "blanket": {
+      "pattern": [
+        "index.js"
+      ],
+      "data-cover-never": [
+        "node_modules",
+        "test"
+      ]
+    }
   },
   "dependencies": {
-    "winston": "0.6.x",
-    "underscore": "~1.5.2"
+    "chalk": "~0.4.0",
+    "underscore": "~1.5.2",
+    "winston": "~1.0.0"
   },
   "devDependencies": {
-    "vows": "0.7.x"
+    "blanket": "~1.1.6",
+    "mocha": "~2.1.0",
+    "node-mocks-http": "~1.2.3",
+    "should": "~4.6.0",
+    "travis-cov": "~0.2.5"
   },
   "engines": {
-    "node": "*"
+    "node": ">=0.6.0"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "contributors": [
+    {
+      "name": "Lars Jacob",
+      "url": "http://jaclar.net"
+    },
+    {
+      "name": "Jonathan Lomas",
+      "url": "http://floatinglomas.ca"
+    },
+    {
+      "name": "Xavier Damman",
+      "url": "http://xdamman.com"
+    },
+    {
+      "name": "Quentin Rossetti",
+      "email": "quentin.rossetti@gmail.com"
+    },
+    {
+      "name": "Robbie Trencheny",
+      "email": "me@robbiet.us",
+      "url": "http://robbie.io"
+    }
+  ]
 }