winston-middleware 3.0.1 → 4.0.1

package/AUTHORS

@@ -7,3 +7,6 @@ Damian Kaczmarek <rush@rushbase.net>
 Robbie Trencheny <me@robbiet.us> (http://robbie.io)
 Ross Brandes <ross.brandes@gmail.com>
 Kévin Maschtaler (https://www.kmaschta.me)
+Matthew Blasius <matthew.blasius@expel.io> (https://expel.io)
+Maxime David <contact@maximedavid.fr>
+Matt Morrissette <yinzara@gmail.com> (https://github.com/yinzara)

package/CHANGELOG.md

@@ -1,3 +1,32 @@
+## 4.0.1
+* Added `headerBlacklist` to BaseLoggerOptions for better typescript support ([#228](https://github.com/bithavoc/winston-middleware/pull/228))
+
+## 4.0.0
+* Changed `metaField` configuration property functionality (see Readme.md) ([#209](https://github.com/bithavoc/winston-middleware/issues/209)) - BREAKING CHANGE
+* Moved type definitions to be embedded inside library ([#123](https://github.com/bithavoc/winston-middleware/issues/123))
+* Added "files" to package.json to reduce unnecessary files in released package
+* Added StackDriver/Google Cloud Logging specific instructions to Readme.md
+* Added `requestField` and `responseField` options to allow storing the request and response in different metadata fields (or not at all) 
+* Fixed `meta` configuration option on `errorLogger` (was not functioning at all)
+* Added .editorconfig and reformatted library to match
+
+## 3.4.0
+* Added: Nested Whitelists ([#225](https://github.com/bithavoc/winston-middleware/pull/225), @kapalex)
+
+## 3.3.0
+* Added: options.headerBlacklist ([#217](https://github.com/bithavoc/winston-middleware/pull/217), @maxday)
+
+## 3.2.1
+* Added: options.skip ([#214](https://github.com/bithavoc/winston-middleware/pull/214), [#147](https://github.com/bithavoc/winston-middleware/pull/147), @ahnkee)
+
+## 3.2.0
+* Replaced: _header -> getHeader ([#210](https://github.com/bithavoc/winston-middleware/pull/210), @Gregoirevda)
+* Replaced coverage tool blanket with nyc ([#211](https://github.com/bithavoc/winston-middleware/pull/211), @golopot)
+* Add eslint and fix lint errors ([#212](https://github.com/bithavoc/winston-middleware/pull/212), @golopot)
+
+## 3.1.0
+* Fix large _.template memory consumption ([#203](https://github.com/bithavoc/winston-middleware/pull/203), @slickmb)
+
 ## 3.0.1
 * Add `format` to `options` to allow user-specified formatting following winston@3 conventions ([#190](https://github.com/bithavoc/winston-middleware/pull/190), @crellison)
 

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2012-2014 Bithavoc.io - http://bithavoc.io
+Copyright (c) 2012 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

@@ -51,9 +51,9 @@ Use `expressWinston.logger(options)` to create a middleware to log your HTTP req
         new winston.transports.Console()
       ],
       format: winston.format.combine(
-        winston.format.colorize()
+        winston.format.colorize(),
         winston.format.json()
-      )
+      ),
       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}}"
       expressFormat: true, // Use the default Express/morgan request formatting. Enabling this will override any msg if true. Will only output colors with colorize set to true
@@ -71,23 +71,25 @@ Use `expressWinston.logger(options)` to create a middleware to log your HTTP req
     format: [<logform.Format>], // formatting desired for log output.
     winstonInstance: <WinstonLogger>, // a winston logger instance. If this is provided the transports and formats options are ignored.
     level: String or function(req, res) { return String; }, // log level to use, the default is "info". Assign a  function to dynamically set the level based on request and response, or a string to statically set it always at that level. statusLevels must be false for this setting to be used.
-    msg: String or function // customize the default logging message. E.g. "{{res.statusCode}} {{req.method}} {{res.responseTime}}ms {{req.url}}", "HTTP {{req.method}} {{req.url}}" or function(req, res) { return `${res.statusCode} - ${req.method}` }
+    msg: String or function, // customize the default logging message. E.g. "{{res.statusCode}} {{req.method}} {{res.responseTime}}ms {{req.url}}", "HTTP {{req.method}} {{req.url}}" or function(req, res) { return `${res.statusCode} - ${req.method}`.  Warning: while supported, returning mustache style interpolation from an options.msg function has performance and memory implications under load.
     expressFormat: Boolean, // Use the default Express/morgan request formatting. Enabling this will override any msg if true. Will only output colors when colorize set to true
     colorize: Boolean, // Color the text and status code, using the Express/morgan color palette (text: gray, status: default green, 3XX cyan, 4XX yellow, 5XX red).
     meta: Boolean, // control whether you want to log the meta data about the request (default to true).
     baseMeta: Object, // default meta data to be added to log, this will be merged with the meta data.
-    metaField: String, // if defined, the meta data will be added in this field instead of the meta root object.
-    statusLevels: Boolean or Object // different HTTP status codes caused log messages to be logged at different levels (info/warn/error), the default is false. Use an object to control the levels various status codes are logged at. Using an object for statusLevels overrides any setting of options.level.
-    ignoreRoute: function (req, res) { return false; } // A function to determine if logging is skipped, defaults to returning false. Called _before_ any later middleware.
-    skip: function(req, res) { return false; } // A function to determine if logging is skipped, defaults to returning false. Called _after_ response has already been sent.
-    requestFilter: function (req, propName) { return req[propName]; } // A function to filter/return request values, defaults to returning all values allowed by whitelist. If the function returns undefined, the key/value will not be included in the meta.
-    responseFilter: function (res, propName) { return res[propName]; } // A function to filter/return response values, defaults to returning all values allowed by whitelist. If the function returns undefined, the key/value will not be included in the meta.
-    requestWhitelist: [String] // Array of request properties to log. Overrides global requestWhitelist for this instance
-    responseWhitelist: [String] // Array of response properties to log. Overrides global responseWhitelist for this instance
-    bodyWhitelist: [String] // Array of body properties to log. Overrides global bodyWhitelist for this instance
-    bodyBlacklist: [String] // Array of body properties to omit from logs. Overrides global bodyBlacklist for this instance
-    ignoredRoutes: [String] // Array of paths to ignore/skip logging. Overrides global ignoredRoutes for this instance
+    metaField: String, // if defined, the meta data will be added in this field instead of the meta root object. Defaults to 'meta'. Set to `null` to store metadata at the root of the log entry.
+    requestField: [String] // the property of the metadata to store the request under (default 'req'). Set to null to exclude request from metadata
+    statusLevels: Boolean or Object, // different HTTP status codes caused log messages to be logged at different levels (info/warn/error), the default is false. Use an object to control the levels various status codes are logged at. Using an object for statusLevels overrides any setting of options.level.
+    ignoreRoute: function (req, res) { return false; }, // A function to determine if logging is skipped, defaults to returning false. Called _before_ any later middleware.
+    skip: function(req, res) { return false; }, // A function to determine if logging is skipped, defaults to returning false. Called _after_ response has already been sent.
+    requestFilter: function (req, propName) { return req[propName]; }, // A function to filter/return request values, defaults to returning all values allowed by whitelist. If the function returns undefined, the key/value will not be included in the meta.
+    responseFilter: function (res, propName) { return res[propName]; }, // A function to filter/return response values, defaults to returning all values allowed by whitelist. If the function returns undefined, the key/value will not be included in the meta.
+    requestWhitelist: [String], // Array of request properties to log. Overrides global requestWhitelist for this instance
+    responseWhitelist: [String], // Array of response properties to log. Overrides global responseWhitelist for this instance
+    bodyWhitelist: [String], // Array of body properties to log. Overrides global bodyWhitelist for this instance
+    bodyBlacklist: [String], // Array of body properties to omit from logs. Overrides global bodyBlacklist for this instance
+    ignoredRoutes: [String], // Array of paths to ignore/skip logging. Overrides global ignoredRoutes for this instance
     dynamicMeta: function(req, res) { return [Object]; } // Extract additional meta data from request or response (typically req.user data if using passport). meta must be true for this function to be activated
+    headerBlacklist: [String], // Array of headers to omit from logs. Applied after any previous filters.
 
 ```
 
@@ -104,7 +106,7 @@ Use `expressWinston.errorLogger(options)` to create a middleware that log the er
         new winston.transports.Console()
       ],
       format: winston.format.combine(
-        winston.format.colorize()
+        winston.format.colorize(),
         winston.format.json()
       )
     }));
@@ -120,19 +122,41 @@ The logger needs to be added AFTER the express router(`app.router)`) and BEFORE
     winstonInstance: <WinstonLogger>, // a winston logger instance. If this is provided the transports and formats options are ignored.
     msg: String or function // customize the default logging message. E.g. "{{err.message}} {{res.statusCode}} {{req.method}}" or function(req, res) { return `${res.statusCode} - ${req.method}` }
     baseMeta: Object, // default meta data to be added to log, this will be merged with the error data.
-    metaField: String, // if defined, the meta data will be added in this field instead of the meta root object.
+    meta: Boolean, // control whether you want to log the meta data about the request (default to true).
+    metaField: String, // if defined, the meta data will be added in this field instead of the meta root object. Defaults to 'meta'. Set to `null` to store metadata at the root of the log entry.
+    requestField: [String] // the property of the metadata to store the request under (default 'req'). Set to null to exclude request from metadata
+    responseField: [String] // the property of the metadata to store the response under (default 'res'). If set to the same as 'requestField', filtered response and request properties will be merged. Set to null to exclude request from metadata    
     requestFilter: function (req, propName) { return req[propName]; } // A function to filter/return request values, defaults to returning all values allowed by whitelist. If the function returns undefined, the key/value will not be included in the meta.
     requestWhitelist: [String] // Array of request properties to log. Overrides global requestWhitelist for this instance
+    headerBlacklist: [String], // Array of headers to omit from logs. Applied after any previous filters.
     level: String or function(req, res, err) { return String; }// custom log level for errors (default is 'error'). Assign a function to dynamically set the log level based on request, response, and the exact error.
     dynamicMeta: function(req, res, err) { return [Object]; } // Extract additional meta data from request or response (typically req.user data if using passport). meta must be true for this function to be activated
     exceptionToMeta: function(error){return Object; } // Function to format the returned meta information on error log. If not given `winston.exception.getAllInfo` will be used by default
     blacklistedMetaFields: [String] // fields to blacklist from meta data
+    skip: function(req, res, err) { return false; } // A function to determine if logging is skipped, defaults to returning 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.
 
+#### `metaField` option
+
+In versions of `winston-middleware` prior to 4.0.0, this field functioned differently.  
+
+Previously the log entry would always have a "meta" field which would be set to the metadata of the request/error.  
+If `metaField` was set, this information would be stored as an object with the given property on the "meta" object of 
+the log entry.  This prevented the use case where the metadata should be located at the root of the log entry.
+
+In this version, `metaField` defaults to "meta" which maintains the prior versions behavior of storing the metadata at 
+a "meta" property of the log entry.  
+
+Explicitly setting the `metaField` to `null` or "null" causes the metadata to be stored at the root of the log entry.
+
+The `metaField` option now also supports dot separated and array values to store the metadata at a nested location in the log entry.
+
+<h3>Upgrade Note: For those upgrading from a version of `winston-middleware` prior to 4.0.0 that use the `metaField` property, to keep the same behavior, prepend `meta.` to your current `metaField` configuration. (i.e. 'foo' would become 'meta.foo')</h3> 
+
 ## Examples
 
 ``` js
@@ -162,7 +186,7 @@ Alternatively, if you're using a winston logger instance elsewhere and have alre
         new winston.transports.Console()
       ],
       format: winston.format.combine(
-        winston.format.colorize()
+        winston.format.colorize(),
         winston.format.json()
       )
     }));
@@ -176,7 +200,7 @@ Alternatively, if you're using a winston logger instance elsewhere and have alre
         new winston.transports.Console()
       ],
       format: winston.format.combine(
-        winston.format.colorize()
+        winston.format.colorize(),
         winston.format.json()
       )
     }));
@@ -295,6 +319,60 @@ Browse `/error` will show you how winston-middleware handles and logs the errors
       "message": "middlewareError"
     }
 
+### StackDriver/Google Cloud Logging
+
+If using this library with `@google-cloud/logging-winston`, use the following configuration to properly store httpRequest information.
+
+See https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry
+
+```javascript
+var express = require('express');
+var expressWinston = require('winston-middleware');
+var LoggingWinston = require('@google-cloud/logging-winston').LoggingWinston;
+
+const app = express()
+
+app.use(expressWinston.logger({
+    transports: [new LoggingWinston({})],
+    metaField: null, //this causes the metadata to be stored at the root of the log entry
+    responseField: null, // this prevents the response from being included in the metadata (including body and status code)
+    requestWhitelist: ['headers', 'query'],  //these are not included in the standard StackDriver httpRequest
+    responseWhitelist: ['body'], // this populates the `res.body` so we can get the response size (not required)
+    dynamicMeta:  (req, res) => {
+      const httpRequest = {}
+      const meta = {}
+      if (req) {
+        meta.httpRequest = httpRequest
+        httpRequest.requestMethod = req.method
+        httpRequest.requestUrl = `${req.protocol}://${req.get('host')}${req.originalUrl}`
+        httpRequest.protocol = `HTTP/${req.httpVersion}`
+        // httpRequest.remoteIp = req.ip // this includes both ipv6 and ipv4 addresses separated by ':'
+        httpRequest.remoteIp = req.ip.indexOf(':') >= 0 ? req.ip.substring(req.ip.lastIndexOf(':') + 1) : req.ip   // just ipv4
+        httpRequest.requestSize = req.socket.bytesRead
+        httpRequest.userAgent = req.get('User-Agent')
+        httpRequest.referrer = req.get('Referrer')
+      }
+    
+      if (res) {
+        meta.httpRequest = httpRequest
+        httpRequest.status = res.statusCode
+        httpRequest.latency = {
+          seconds: Math.floor(res.responseTime / 1000),
+          nanos: ( res.responseTime % 1000 ) * 1000000
+        }
+        if (res.body) {
+          if (typeof res.body === 'object') {
+            httpRequest.responseSize = JSON.stringify(res.body).length
+          } else if (typeof res.body === 'string') {
+            httpRequest.responseSize = res.body.length
+          }
+        }
+      }
+      return meta
+    }
+}));
+```
+
 ## Global Whitelists and Blacklists
 
 winston-middleware exposes three whitelists that control which properties of the `request`, `body`, and `response` are logged:
@@ -324,6 +402,40 @@ Note that you can log the whole request and/or response body:
 
     expressWinston.requestWhitelist.push('body');
     expressWinston.responseWhitelist.push('body');
+    
+### Nested Whitelists
+
+`requestWhitelist` and `responseWhitelist` also support nested whitelist values, allowing access to parts of an object.
+
+For example, using the following during logger setup:
+
+    expressWinston.responseWhitelist.push('body.import.value');
+    
+A response that looks like this :
+
+    {
+        body: {
+            important: {
+                value: 5
+            },
+            notImportant: {
+                value: 7
+            }
+        },
+        other: {
+            value: 3
+        }
+    }
+    
+Would only log the following value :
+
+    {
+        body: {
+            important: {
+                value: 5
+            }
+        }
+    }
 
 ## Route-Specific Whitelists and Blacklists
 
@@ -439,13 +551,9 @@ Run the basic Mocha tests:
 
     npm test
 
-Run the Travis-CI tests (which will fail with < 100% coverage):
-
-    npm run test-travis
-
-Generate the `coverage.html` coverage report:
+View the coverage report:
 
-    npm run test-coverage
+    npx http-server coverage/lcov-report
 
 ## Issues and Collaboration
 
@@ -457,12 +565,14 @@ If you ran into any problems, please use the project [Issues section](https://gi
 * [Lars Jacob](https://github.com/jaclar) (https://github.com/jaclar)
 * [Jonathan Lomas](https://github.com/floatingLomas) (https://github.com/floatingLomas)
 * [Ross Brandes](https://github.com/rosston) (https://github.com/rosston)
+* [Alex Kaplan](https://github.com/kapalex) (https://github.com/kapalex)
+* [Matt Morrissette](https://github.com/yinzara) (https://github.com/yinzara) 
 
 Also see AUTHORS file, add yourself if you are missing.
 
 ## MIT License
 
-Copyright (c) 2012-2014 Bithavoc.io and Contributors - http://bithavoc.io
+Copyright (c) 2012 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.d.ts

@@ -0,0 +1,115 @@
+// Type definitions for winston-middleware 4.0
+// Project: https://github.com/bithavoc/winston-middleware#readme
+// Definitions by: Alex Brick <https://github.com/bricka>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+// TypeScript Version: 2.3
+
+import { ErrorRequestHandler, Handler, Request, Response } from 'express';
+import { Format } from 'logform';
+import * as winston from 'winston';
+import * as Transport from 'winston-transport';
+
+export interface FilterRequest extends Request {
+    [other: string]: any;
+}
+
+export interface FilterResponse extends Response {
+    [other: string]: any;
+}
+
+export type DynamicMetaFunction = (req: Request, res: Response, err: Error) => object;
+export type DynamicLevelFunction = (req: Request, res: Response, err: Error) => string;
+export type RequestFilter = (req: FilterRequest, propName: string) => any;
+export type ResponseFilter = (res: FilterResponse, propName: string) => any;
+export type RouteFilter = (req: Request, res: Response) => boolean;
+export type MessageTemplate = string | ((req: Request, res: Response) => string);
+
+export interface BaseLoggerOptions {
+    baseMeta?: object;
+    bodyBlacklist?: string[];
+    bodyWhitelist?: string[];
+    colorize?: boolean;
+    dynamicMeta?: DynamicMetaFunction;
+    expressFormat?: boolean;
+    format?: Format;
+    ignoreRoute?: RouteFilter;
+    ignoredRoutes?: string[];
+    level?: string | DynamicLevelFunction;
+    meta?: boolean;
+    metaField?: string;
+    requestField?: string;
+    responseField?: string;
+    msg?: MessageTemplate;
+    requestFilter?: RequestFilter;
+    requestWhitelist?: string[];
+    responseFilter?: ResponseFilter;
+    responseWhitelist?: string[];
+    headerBlacklist?: string[];
+    skip?: RouteFilter;
+    statusLevels?: {
+        error?: string;
+        success?: string;
+        warn?: string;
+    };
+}
+
+export interface LoggerOptionsWithTransports extends BaseLoggerOptions {
+    transports: Transport[];
+}
+
+export interface LoggerOptionsWithWinstonInstance extends BaseLoggerOptions {
+    winstonInstance: winston.Logger;
+}
+
+export type LoggerOptions = LoggerOptionsWithTransports | LoggerOptionsWithWinstonInstance;
+
+export function logger(options: LoggerOptions): Handler;
+
+export interface BaseErrorLoggerOptions {
+    baseMeta?: object;
+    dynamicMeta?: DynamicMetaFunction;
+    format?: Format;
+    level?: string | DynamicLevelFunction;
+    meta?: boolean;
+    metaField?: string;
+    requestField?: string;
+    msg?: MessageTemplate;
+    requestFilter?: RequestFilter;
+    requestWhitelist?: string[];
+}
+
+export interface ErrorLoggerOptionsWithTransports extends BaseErrorLoggerOptions {
+    transports: Transport[];
+}
+
+export interface ErrorLoggerOptionsWithWinstonInstance extends BaseErrorLoggerOptions {
+    winstonInstance: winston.Logger;
+}
+
+export type ErrorLoggerOptions = ErrorLoggerOptionsWithTransports | ErrorLoggerOptionsWithWinstonInstance;
+
+export function errorLogger(options: ErrorLoggerOptions): ErrorRequestHandler;
+
+export let requestWhitelist: string[];
+
+export let bodyWhitelist: string[];
+
+export let bodyBlacklist: string[];
+
+export let responseWhitelist: string[];
+
+export let ignoredRoutes: string[];
+
+export let defaultRequestFilter: RequestFilter;
+
+export let defaultResponseFilter: ResponseFilter;
+
+export function defaultSkip(): boolean;
+
+export interface ExpressWinstonRequest extends Request {
+    _routeWhitelists: {
+        body: string[];
+        req: string[];
+        res: string[];
+    };
+}