winston-middleware 0.1.0

package/.travis.yml

@@ -0,0 +1,5 @@
+language: node_js
+node_js:
+  - 0.6
+  - 0.8
+script: "npm test"

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2012 Firebase.co - 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
+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.

package/Readme.md

@@ -0,0 +1,240 @@
+# winston-middleware
+[![Build Status](https://secure.travis-ci.org/firebaseco/winston-middleware.png)](http://travis-ci.org/firebaseco/winston-middleware)
+
+> [winston](https://github.com/flatiron/winston) middleware for express.js
+
+## Installation
+
+    npm install winston-middleware
+
+## Usage
+
+winston-middleware provides middlewares for request and error logging of your express.js application.
+
+### Error Logging
+
+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.
+    app.use(expressWinston.errorHandler({
+      transports: [
+        new winston.transports.Console({
+          json: true,
+          colorize: true
+        })
+      ]
+    }));
+```
+
+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.
+
+### Request Logging
+
+Use `expressWinston.logger(options)` to create a middleware to log your HTTP requests.
+
+``` js
+
+    app.use(expressWinston.logger({
+      transports: [
+        new winston.transports.Console({
+          json: true,
+          colorize: true
+        })
+      ]
+    }));
+    app.use(app.router); // notice how the router goes after the logger.
+```
+
+## Example
+
+``` js 
+    var express = require('express');
+    var expressWinston = require('winston-middleware');
+    var winston = require('winston'); // for transports.Console
+    var app = module.exports = express.createServer();
+
+    app.use(express.bodyParser());
+    app.use(express.methodOverride());
+
+    // winston-middleware logger makes sense BEFORE the router.
+    app.use(expressWinston.logger({
+      transports: [
+        new winston.transports.Console({
+          json: true,
+          colorize: true
+        })
+      ]
+    }));
+
+    app.use(app.router);
+
+    // winston-middleware errorHandler makes sense AFTER the router.
+    app.use(expressWinston.errorHandler({
+      transports: [
+        new winston.transports.Console({
+          json: true,
+          colorize: true
+        })
+      ]
+    }));
+
+    // Optionally you can include your custom error handler after the logging.
+    app.use(express.errorHandler({
+      dumpExceptions: true,
+      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);
+    });
+```
+
+Browse `/` to see a regular HTTP logging like this:
+
+    {
+      "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": {}
+      },
+      "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:
+
+    {
+      "date": "Thu Jul 19 2012 23:39:44 GMT-0500 (COT)",
+      "process": {
+        "pid": 35719,
+        "uid": 501,
+        "gid": 20,
+        "cwd": "/Users/thepumpkin/Projects/testExpressWinston",
+        "execPath": "/usr/local/bin/node",
+        "version": "v0.6.18",
+        "argv": [
+          "node",
+          "/Users/thepumpkin/Projects/testExpressWinston/app.js"
+        ],
+        "memoryUsage": {
+          "rss": 14749696,
+          "heapTotal": 7033664,
+          "heapUsed": 5213280
+        }
+      },
+      "os": {
+        "loadavg": [
+          1.95068359375,
+          1.5166015625,
+          1.38671875
+        ],
+        "uptime": 498086
+      },
+      "trace": [
+        ...,
+        {
+          "column": 3,
+          "file": "Object].log (/Users/thepumpkin/Projects/testExpressWinston/node_modules/winston/lib/winston/transports/console.js",
+          "function": "[object",
+          "line": 87,
+          "method": null,
+          "native": false
+        }
+      ],
+      "stack": [
+        "Error: This is an error and it should be logged to the console",
+        "    at /Users/thepumpkin/Projects/testExpressWinston/app.js:39:15",
+        "    at callbacks (/Users/thepumpkin/Projects/testExpressWinston/node_modules/express/lib/router/index.js:272:11)",
+        "    at param (/Users/thepumpkin/Projects/testExpressWinston/node_modules/express/lib/router/index.js:246:11)",
+        "    at pass (/Users/thepumpkin/Projects/testExpressWinston/node_modules/express/lib/router/index.js:253:5)",
+        "    at Router._dispatch (/Users/thepumpkin/Projects/testExpressWinston/node_modules/express/lib/router/index.js:280:4)",
+        "    at Object.handle (/Users/thepumpkin/Projects/testExpressWinston/node_modules/express/lib/router/index.js:45:10)",
+        "    at next (/Users/thepumpkin/Projects/testExpressWinston/node_modules/express/node_modules/connect/lib/http.js:204:15)",
+        "    at done (/Users/thepumpkin/Dropbox/Projects/winston-middleware/index.js:91:14)",
+        "    at /Users/thepumpkin/Dropbox/Projects/winston-middleware/node_modules/async/lib/async.js:94:25",
+        "    at [object Object].log (/Users/thepumpkin/Projects/testExpressWinston/node_modules/winston/lib/winston/transports/console.js:87:3)"
+      ],
+      "req": {
+        "httpVersion": "1.1",
+        "headers": {
+          "host": "localhost:3000",
+          "connection": "keep-alive",
+          "cache-control": "max-age=0",
+          "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": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+          "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%2B6WhmcwdzFEjqhMDuIIl3mAUY7dT4vn%2BkWvRPhZc"
+        },
+        "url": "/error",
+        "method": "GET",
+        "originalUrl": "/error",
+        "query": {}
+      },
+      "level": "error",
+      "message": "middlewareError"
+    }
+
+## 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.
+
+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*
+
+## MIT License
+
+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
+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.

package/index.js

@@ -0,0 +1,104 @@
+// 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
+// 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.
+//
+
+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?
+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];
+};
+
+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;
+};
+
+// 
+// ### 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);
+    };
+    // 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;
+  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('info', msg, meta, nextTransport);
+    };
+
+    function done() {
+      return next();
+    };
+    // iterate all the transports
+    async.forEach(options.transports, logOnTransport, done);
+  };
+};
+
+module.exports.errorLogger = errorLogger;
+module.exports.logger = logger;
+module.exports.requestWhitelist = requestWhitelist;
+module.exports.defaultRequestFilter = defaultRequestFilter;

package/package.json

@@ -0,0 +1,30 @@
+{
+  "author": "Firebase.co <npm@firebase.co> (http://www.firebase.co/)",
+  "name": "winston-middleware",
+  "description": "express.js middleware for flatiron/winston",
+  "keywords": ["winston", "flatiron", "logging", "express", "log", "error", "handler", "middleware"],
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/firebaseco/winston-middleware.git"
+  },
+  "main": "index.js",
+  "scripts": {
+    "test": "node test/test.js"
+  },
+  "dependencies": {
+    "winston": "0.6.x",
+    "async": "0.1.x"
+  },
+  "devDependencies": {
+    "vows": "0.6.x"
+  },
+  "engines": {
+    "node": "0.6.x"
+  },
+	"licenses" : [
+		{
+			"type" : "MIT", 
+			"url" : "https://github.com/firebaseco/winston-middleware/blob/master/LICENSE"
+		}
+	]
+}

package/test/test.js

@@ -0,0 +1,243 @@
+var vows = require('vows');
+var assert = require('assert');
+var winston = require('winston');
+var expressWinston = require('../index');
+var util = require('util');
+var events = require('events');
+
+var MockTransport = function(options) {
+  winston.Transport.call(this, options);
+};
+util.inherits(MockTransport, winston.Transport);
+
+vows.describe("exports").addBatch({
+  "When I check the exported properties": {
+    topic: function() {
+      return expressWinston;
+    },
+    "an array with all the properties whilelist in the req object": function(exports) {
+      assert.isArray(exports.requestWhitelist);
+    },
+    "and the factory should contain a default request filter function": function(exports) {
+      assert.isFunction(exports.defaultRequestFilter);
+    },
+    "it should export a function for the creation of error loggers middlewares": function(exports) {
+      assert.isFunction(exports.errorLogger);
+    },
+    "it should export a function for the creation of request logger middlewares": function(exports) {
+      assert.isFunction(exports.logger);
+    }
+  }
+}).export(module);
+
+vows.describe("errorLogger").addBatch({
+  "when I run the middleware factory": {
+    topic: function() {
+      return expressWinston.errorLogger;
+    },
+    "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 four arguments that fit err, req, res, next": function (factory) {
+        var middleware = factory({
+          transports: [
+            new MockTransport({
+              
+            })
+          ]
+        });
+        assert.equal(middleware.length, 4);
+      }
+    }
+  },
+  "When the winston-middleware middleware encounter an error in the pipeline": {
+    topic: function() {
+      var factory = expressWinston.errorLogger;
+      var callback = this.callback;
+      var req = {
+        url: "/hello?val=1",
+        headers: {
+          'header-1': 'value 1'
+        },
+        method: 'GET',
+        query: {
+          val: '1'
+        },
+        originalUrl: "/hello?val=1",
+        params: {
+          id: 20
+        },
+        filteredProperty: "value that should not be logged"
+      };
+      var res = {
+
+      };
+      var originalError = new Error("This is the Error");
+      var test = {
+        req: req,
+        res: res,
+        log: {},
+        originalError: originalError,
+        pipelineError: null
+      };
+      var next = function(pipelineError) {
+        test.pipelineError = pipelineError;
+        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(originalError, req, res, next);
+    }
+    , "then the transport should be invoked": function(result){
+      assert.isTrue(result.transportInvoked);
+    }
+    , "the error level should be error": function(result){
+      assert.equal(result.log.level, "error");
+    }
+    , "the msg should be middlewareError": function(result){
+      assert.equal(result.log.msg, "middlewareError");
+    }
+    , "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: '1'
+      });
+      assert.isUndefined(result.log.meta.req.filteredProperty);
+    },
+    "the winston-middleware middleware should not swallow the pipeline error": function(result) {
+      assert.isNotNull(result.pipelineError);
+      assert.strictEqual(result.pipelineError, result.originalError);
+    }
+  }
+}).export(module);
+
+vows.describe("logger").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
+        },
+        filteredProperty: "value that should not be logged"
+      };
+      var res = {
+
+      };
+      var test = {
+        req: req,
+        res: res,
+        log: {}
+      };
+      var next = function() {
+        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.filteredProperty);
+    }
+  }
+}).export(module);