strong-error-handler 1.2.1 → 2.3.0

package/.github/ISSUE_TEMPLATE.md

@@ -1,36 +1,37 @@
 <!--
-- Please ask questions at https://groups.google.com/forum/#!forum/loopbackjs or
+Questions:
+  https://groups.google.com/forum/#!forum/loopbackjs
   https://gitter.im/strongloop/loopback
-
-- Immediate support is available through our subscription plans, see
+Immediate support:
   https://strongloop.com/api-connect-faqs/
+  https://strongloop.com/node-js/subscription-plans/
 -->
 
-### Bug or feature request
+# Description/Steps to reproduce
 
 <!--
-Mark your choice with an "x" (eg. [x], NOT [*]).
+If feature: A description of the feature
+If bug: Steps to reproduce
 -->
 
-- [ ] Bug
-- [ ] Feature request
-
-### Description of feature (or steps to reproduce if bug)
-
-
-
-### Link to sample repo to reproduce issue (if bug)
-
-
-
-### Expected result
+# Link to reproduction sandbox
 
+<!--
+Link to an app sandbox for reproduction
 
+Note: Failure to provide a sandbox application for reproduction purposes will result in the issue being closed.
+-->
 
-### Actual result (if bug)
-
-
+# Expected result
 
-### Additional information (Node.js version, LoopBack version, etc)
+<!--
+Also include actual results if bug
+-->
 
+# Additional information
 
+<!--
+Copy+paste the output of these two commands:
+  node -e 'console.log(process.platform, process.arch, process.versions.node)'
+  npm ls --prod --depth 0 | grep loopback
+-->

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -6,17 +6,18 @@
 <!--
 Please use the following link syntaxes:
 
-- #49 (to reference issues in the current repository)
-- strongloop/loopback#49 (to reference issues in another repository)
+- connect to #49 (to reference issues in the current repository)
+- connect to strongloop/loopback#49 (to reference issues in another repository)
 -->
 
-- None
+- connect to <link_to_referenced_issue>
 
 ### Checklist
 
 <!--
-Please mark your choice with an "x" (i.e. [x], see
+- Please mark your choice with an "x" (i.e. [x], see
 https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-comments)
+- PR's without test coverage will be closed.
 -->
 
 - [ ] New tests added or existing tests modified to cover all changes

package/CHANGES.md

@@ -1,3 +1,47 @@
+2017-10-13, Version 2.3.0
+=========================
+
+ * update strong-globalize to 3.1.0 (shimks)
+
+ * CODEOWNERS: add zbarbuto (Miroslav Bajtoš)
+
+ * Update Issue and PR Templates (#59) (Sakib Hasan)
+
+ * fixed json typo of server/middleware.json (karanssj4)
+
+ * Add CODEOWNER file (Diana Lau)
+
+
+2017-07-20, Version 2.2.0
+=========================
+
+ * Add new option: negotiateContentType (Raj)
+
+
+2017-04-18, Version 2.1.0
+=========================
+
+ * Bump js2xmlparser dependency to version 3.0.0 (Matthew O'Donoghue)
+
+
+2017-03-22, Version 2.0.0
+=========================
+
+ * Fix markdown formatting in README (Miroslav Bajtoš)
+
+ * Fix the order of arguments in the jsdoc comment. (Charlie Schliesser)
+
+ * Update readme with added XML support (David Cheung)
+
+ * Add a machine-readable "code" property (Zak Barbuto)
+
+ * Upgrade dependencies to their latest versions (Miroslav Bajtoš)
+
+ * Describe "safeFields" option in README (Zak Barbuto)
+
+ * Drop support for Node v0.10/v0.12 (Miroslav Bajtoš)
+
+
 2017-01-30, Version 1.2.1
 =========================
 

package/CODEOWNERS

@@ -0,0 +1,5 @@
+# Lines starting with '#' are comments.
+# Each line is a file pattern followed by one or more owners,
+# the last matching pattern has the most precendence.
+
+* @bajtos @zbarbuto

package/README.md

@@ -7,7 +7,8 @@ In production mode, `strong-error-handler` omits details from error responses to
 - For 5xx errors, the output contains only the status code and the status name from the HTTP specification.
 - For 4xx errors, the output contains the full error message (`error.message`) and the contents of the `details`
   property (`error.details`) that `ValidationError` typically uses to provide machine-readable details
-  about validation problems.
+  about validation problems. It also includes `error.code` to allow a machine-readable error code to be passed
+  through which could be used, for example, for translation.
 
 In debug mode, `strong-error-handler` returns full error stack traces and internal details of any error objects to the client in the HTTP responses.
 
@@ -59,7 +60,7 @@ For details on configuration options, see below.
 
 ### Response format and content type
 
-The `strong-error-handler` package supports HTML and JSON responses:
+The `strong-error-handler` package supports JSON, HTML and XML responses:
 
 - When the object is a standard Error object, it returns the string provided by the stack property in HTML/text
   responses.
@@ -70,8 +71,9 @@ The content type of the response depends on the request's `Accepts` header.
 
 -  For Accepts header `json` or `application/json`, the response content type is JSON.
 -  For Accepts header `html` or `text/html`, the response content type is HTML.
+-  For Accepts header `xml` or `text/xml`, the response content type is XML.
 
-*There are plans to support other formats such as Text and XML.*
+*There are plans to support other formats such as Plain-text.*
 
 ## Options
 
@@ -79,6 +81,9 @@ The content type of the response depends on the request's `Accepts` header.
 | ---- | ---- | ---- | ---- |
 | debug | Boolean    | `false` | If `true`, HTTP responses include all error properties, including sensitive data such as file paths, URLs and stack traces. See [Example output](#example) below. |
 | log | Boolean | `true` |  If `true`, all errors are printed via `console.error`, including an array of fields (custom error properties) that are safe to include in response messages (both 4xx and 5xx). <br/> If `false`, sends only the error back in the response. |
+| safeFields | [String] | `[]` |  Specifies property names on errors that are allowed to be passed through in 4xx and 5xx responses. See [Safe error fields](#safe-error-fields) below. |
+| defaultType | String | `"json"` | Specify the default response content type to use when the client does not provide any Accepts header.
+| negotiateContentType | Boolean | true | Negotiate the response content type via Accepts request header. When disabled, strong-error-handler will always use the default content type when producing responses. Disabling content type negotiation is useful if you want to see JSON-formatted error responses in browsers, because browsers usually prefer HTML and XML over other content types.
 
 ### Customizing log format
 
@@ -116,7 +121,7 @@ Then in `server/middleware.json`, specify your custom error logging function as
     "./middleware/error-logger": {},
     "strong-error-handler": {
       "params": {
-        log: false
+        "log": false
       }
     }
 }
@@ -124,6 +129,34 @@ Then in `server/middleware.json`, specify your custom error logging function as
 
 The default `middleware.development.json` file explicitly enables logging in strong-error-handler params, so you will need to change that file too.
 
+### Safe error fields
+
+By default, `strong-error-handler` will only pass through the `name`, `message` and `details` properties of an error. Additional error
+properties may be allowed through on 4xx and 5xx status code errors using the `safeFields` option to pass in an array of safe field names:
+
+```
+{
+  "final:after": {
+    "strong-error-handler": {
+      "params": {
+        "safeFields": ["errorCode"]
+      }
+    }
+}
+```
+
+Using the above configuration, an error containing an `errorCode` property will produce the following response:
+
+```
+{
+  "error": {
+    "statusCode": 500,
+    "message": "Internal Server Error",
+    "errorCode": "INTERNAL_SERVER_ERROR"
+  }
+}
+```
+
 ## Migration from old LoopBack error handler
 
 NOTE: This is only required for applications scaffolded with old versions of the `slc loopback` tool.
@@ -140,34 +173,34 @@ To migrate a LoopBack 2.x application to use `strong-error-handler`:
       "errorHandler": {
         "disableStackTrace": false
       }</pre>
-  and replace it with:
-  <pre>
-  "remoting": {
-    ...,
-    "rest": {
-      "handleErrors": false
-    }</pre>
+    and replace it with:
+    <pre>
+    "remoting": {
+      ...,
+      "rest": {
+        "handleErrors": false
+      }</pre>
 1. In `server/middleware.json`, remove:
     <pre>
     "final:after": {
       "loopback#errorHandler": {}
     }</pre>
-  and replace it with:
+    and replace it with:
     <pre>
     "final:after": {
       "strong-error-handler": {}
     }</pre>
 1. Delete `server/middleware.production.json`.
 1. Create `server/middleware.development.json` containing:
-  <pre>
-  "final:after": {
-    "strong-error-handler": {
-      "params": {
-        "debug": true,
-        "log": true
+    <pre>
+    "final:after": {
+      "strong-error-handler": {
+        "params": {
+          "debug": true,
+          "log": true
+        }
       }
     }
-  }
 </pre>
 
 For more information, see 
@@ -175,13 +208,13 @@ For more information, see
 
 ## Example
 
-Error generated when `debug: false` :
+5xx error generated when `debug: false` :
 
 ```
 { error: { statusCode: 500, message: 'Internal Server Error' } }
 ```
 
-Error generated when `debug: true` :
+The same error generated when `debug: true` :
 
 ```
 { error:
@@ -201,3 +234,13 @@ Error generated when `debug: true` :
   at tryOnImmediate (timers.js:543:15)    
   at processImmediate [as _immediateCallback] (timers.js:523:5)' }}
 ```
+
+4xx error generated when `debug: false` :
+
+```
+{ error:
+  { statusCode: 422,
+  name: 'Unprocessable Entity',
+  message: 'Missing required fields',
+  code: 'MISSING_REQUIRED_FIELDS' }}
+```

package/lib/content-negotiation.js

@@ -18,10 +18,11 @@ module.exports = negotiateContentProducer;
  * to resolve the correct operation
  *
  * @param req request object
+ * @param {Function} logWarning a logger function for reporting warnings
  * @param {Object} options options of strong-error-handler
- * @returns {Function} Opeartion function with signature `fn(res, data)`
+ * @returns {Function} Operation function with signature `fn(res, data)`
  */
-function negotiateContentProducer(req, options) {
+function negotiateContentProducer(req, logWarning, options) {
   var SUPPORTED_TYPES = [
     'application/json', 'json',
     'text/html', 'html',
@@ -55,6 +56,18 @@ function negotiateContentProducer(req, options) {
   debug('Resolved content-type', resolvedContentType);
   var contentType = resolvedContentType || defaultType;
 
+  if (options.negotiateContentType === false) {
+    if (SUPPORTED_TYPES.indexOf(options.defaultType) > -1) {
+      debug('Forcing options.defaultType `%s`',
+        options.defaultType);
+      contentType = options.defaultType;
+    } else {
+      debug('contentType: `%s` is not supported, ' +
+        'falling back to contentType: `%s`',
+         options.defaultType, contentType);
+    }
+  }
+
   // to receive _format from user's url param to overide the content type
   // req.query (eg /api/Users/1?_format=json will overide content negotiation
   // https://github.com/strongloop/strong-remoting/blob/ac3093dcfbb787977ca0229b0f672703859e52e1/lib/http-context.js#L643-L645
@@ -66,8 +79,7 @@ function negotiateContentProducer(req, options) {
       // format passed through query but not supported
       var msg = util.format('Response _format "%s" is not supported' +
         'used "%s" instead"', query._format, defaultType);
-      res.header('X-Warning', msg);
-      debug(msg);
+      logWarning(msg);
     }
   }
 

package/lib/data-builder.js

@@ -77,6 +77,7 @@ function fillDebugData(data, err) {
 function fillBadRequestError(data, err) {
   data.name = err.name;
   data.message = err.message;
+  data.code = err.code;
   data.details = err.details;
 }
 

package/lib/handler.js

@@ -51,7 +51,12 @@ exports = module.exports = function createStrongErrorHandler(options) {
     res.setHeader('X-Content-Type-Options', 'nosniff');
     res.statusCode = data.statusCode;
 
-    var sendResponse = negotiateContentProducer(req, options);
+    var sendResponse = negotiateContentProducer(req, warn, options);
     sendResponse(res, data);
+
+    function warn(msg) {
+      res.header('X-Warning', msg);
+      debug(msg);
+    }
   };
 };

package/package.json

@@ -2,7 +2,10 @@
   "name": "strong-error-handler",
   "description": "Error handler for use in development and production environments.",
   "license": "MIT",
-  "version": "1.2.1",
+  "version": "2.3.0",
+  "engines": {
+    "node": ">=4"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/strongloop/strong-error-handler.git"
@@ -17,17 +20,17 @@
     "accepts": "^1.3.3",
     "debug": "^2.2.0",
     "ejs": "^2.4.2",
-    "http-status": "^0.2.2",
-    "js2xmlparser": "^2.0.2",
-    "strong-globalize": "^2.6.7"
+    "http-status": "^1.0.0",
+    "js2xmlparser": "^3.0.0",
+    "strong-globalize": "^3.1.0"
   },
   "devDependencies": {
-    "chai": "^2.1.1",
-    "eslint": "^2.13.1",
-    "eslint-config-loopback": "^4.0.0",
+    "chai": "^3.5.0",
+    "eslint": "^3.14.1",
+    "eslint-config-loopback": "^8.0.0",
     "express": "^4.13.4",
-    "mocha": "^2.1.0",
-    "supertest": "^1.1.0"
+    "mocha": "^3.2.0",
+    "supertest": "^3.0.0"
   },
   "browser": {
     "strong-error-handler": false

package/.npmignore

@@ -1,35 +0,0 @@
-# Logs
-logs
-*.log
-npm-debug.log*
-
-# Runtime data
-pids
-*.pid
-*.seed
-
-# Directory for instrumented libs generated by jscoverage/JSCover
-lib-cov
-
-# Coverage directory used by tools like istanbul
-coverage
-
-# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
-.grunt
-
-# node-waf configuration
-.lock-wscript
-
-# Compiled binary addons (http://nodejs.org/api/addons.html)
-build/Release
-
-# Dependency directory
-node_modules
-
-# Optional npm cache directory
-.npm
-
-# Optional REPL history
-.node_repl_history
-test
-.travis.yml