@tryghost/errors 0.2.14 → 1.0.0

package/lib/errors.js

@@ -1,17 +1,203 @@
+const uuid = require('uuid');
 const merge = require('lodash/merge');
-const each = require('lodash/each');
-const util = require('util');
-const errors = require('@tryghost/ignition-errors');
+const isString = require('lodash/isString');
+const utils = require('./utils');
 
-class GhostError extends errors.IgnitionError {
+class GhostError extends Error {
     constructor(options) {
         options = options || {};
-        super(options);
-        this.value = options.value;
+
+        super();
+
+        /**
+         * defaults
+         */
+        this.statusCode = 500;
+        this.errorType = 'InternalServerError';
+        this.level = 'normal';
+        this.message = 'The server has encountered an error.';
+        this.id = uuid.v1();
+
+        /**
+         * custom overrides
+         */
+        this.id = options.id || this.id;
+        this.statusCode = options.statusCode || this.statusCode;
+        this.level = options.level || this.level;
+        this.context = options.context || this.context;
+        this.help = options.help || this.help;
+        this.errorType = this.name = options.errorType || this.errorType;
+        this.errorDetails = options.errorDetails;
+        // @ts-ignore
+        this.code = options.code || null;
+        this.property = options.property || null;
+        this.redirect = options.redirect || null;
+
+        this.message = options.message || this.message;
+        this.hideStack = options.hideStack;
+
+        // NOTE: Error to inherit from, override!
+        //       Nested objects are getting copied over in one piece (can be changed, but not needed right now)
+        if (options.err) {
+            // CASE: Support err as string (it happens that third party libs return a string instead of an error instance)
+            if (isString(options.err)) {
+                /* eslint-disable no-restricted-syntax */
+                options.err = new Error(options.err);
+                /* eslint-enable no-restricted-syntax */
+            }
+
+            Object.getOwnPropertyNames(options.err).forEach((property) => {
+                if (['errorType', 'name', 'statusCode', 'message', 'level'].indexOf(property) !== -1) {
+                    return;
+                }
+
+                // CASE: `code` should put options as priority over err
+                if (property === 'code') {  
+                    // @ts-ignore
+                    this[property] = this[property] || options.err[property];
+                    return;
+                }
+
+                if (property === 'stack') {
+                    this[property] += '\n\n' + options.err[property];
+                    return;
+                }
+
+                this[property] = options.err[property] || this[property];
+            });
+        }
     }
 }
 
 const ghostErrors = {
+    InternalServerError: class InternalServerError extends GhostError {
+        constructor(options) {
+            super(merge({
+                statusCode: 500,
+                level: 'critical',
+                errorType: 'InternalServerError',
+                message: 'The server has encountered an error.'
+            }, options));
+        }
+    },
+    IncorrectUsageError: class IncorrectUsageError extends GhostError {
+        constructor(options) {
+            super(merge({
+                statusCode: 400,
+                level: 'critical',
+                errorType: 'IncorrectUsageError',
+                message: 'We detected a misuse. Please read the stack trace.'
+            }, options));
+        }
+    },
+    NotFoundError: class NotFoundError extends GhostError {
+        constructor(options) {
+            super(merge({
+                statusCode: 404,
+                errorType: 'NotFoundError',
+                message: 'Resource could not be found.'
+            }, options));
+        }
+    },
+    BadRequestError: class BadRequestError extends GhostError {
+        constructor(options) {
+            super(merge({
+                statusCode: 400,
+                errorType: 'BadRequestError',
+                message: 'The request could not be understood.'
+            }, options));
+        }
+    },
+    UnauthorizedError: class UnauthorizedError extends GhostError {
+        constructor(options) {
+            super(merge({
+                statusCode: 401,
+                errorType: 'UnauthorizedError',
+                message: 'You are not authorised to make this request.'
+            }, options));
+        }
+    },
+    NoPermissionError: class NoPermissionError extends GhostError {
+        constructor(options) {
+            super(merge({
+                statusCode: 403,
+                errorType: 'NoPermissionError',
+                message: 'You do not have permission to perform this request.'
+            }, options));
+        }
+    },
+    ValidationError: class ValidationError extends GhostError {
+        constructor(options) {
+            super(merge({
+                statusCode: 422,
+                errorType: 'ValidationError',
+                message: 'The request failed validation.'
+            }, options));
+        }
+    },
+    UnsupportedMediaTypeError: class UnsupportedMediaTypeError extends GhostError {
+        constructor(options) {
+            super(merge({
+                statusCode: 415,
+                errorType: 'UnsupportedMediaTypeError',
+                message: 'The media in the request is not supported by the server.'
+            }, options));
+        }
+    },
+    TooManyRequestsError: class TooManyRequestsError extends GhostError {
+        constructor(options) {
+            super(merge({
+                statusCode: 429,
+                errorType: 'TooManyRequestsError',
+                message: 'Server has received too many similar requests in a short space of time.'
+            }, options));
+        }
+    },
+    MaintenanceError: class MaintenanceError extends GhostError {
+        constructor(options) {
+            super(merge({
+                statusCode: 503,
+                errorType: 'MaintenanceError',
+                message: 'The server is temporarily down for maintenance.'
+            }, options));
+        }
+    },
+    MethodNotAllowedError: class MethodNotAllowedError extends GhostError {
+        constructor(options) {
+            super(merge({
+                statusCode: 405,
+                errorType: 'MethodNotAllowedError',
+                message: 'Method not allowed for resource.'
+            }, options));
+        }
+    },
+    RequestEntityTooLargeError: class RequestEntityTooLargeError extends GhostError {
+        constructor(options) {
+            super(merge({
+                statusCode: 413,
+                errorType: 'RequestEntityTooLargeError',
+                message: 'Request was too big for the server to handle.'
+            }, options));
+        }
+    },
+    TokenRevocationError: class TokenRevocationError extends GhostError {
+        constructor(options) {
+            super(merge({
+                statusCode: 503,
+                errorType: 'TokenRevocationError',
+                message: 'Token is no longer available.'
+            }, options));
+        }
+    },
+    VersionMismatchError: class VersionMismatchError extends GhostError {
+        constructor(options) {
+            super(merge({
+                statusCode: 400,
+                errorType: 'VersionMismatchError',
+                message: 'Requested version does not match server version.'
+            }, options));
+        }
+    },
     DataExportError: class DataExportError extends GhostError {
         constructor(options) {
             super(merge({
@@ -95,17 +281,21 @@ const ghostErrors = {
                 message: 'For security, you need to create a new password. An email has been sent to you with instructions!'
             }, options));
         }
+    },
+    UnhandledJobError: class UnhandledJobError extends GhostError {
+        constructor(options) {
+            super(merge({
+                errorType: 'UnhandledJobError',
+                message: 'Processed job threw an unhandled error',
+                level: 'critical'
+            }, options));
+        }
     }
 };
 
-// we need to inherit all general errors from GhostError, otherwise we have to check instanceof IgnitionError
-each(errors, function (error) {
-    if (error.name === 'IgnitionError' || typeof error === 'object') {
-        return;
-    }
-
-    util.inherits(error, GhostError);
-});
-
-module.exports = merge(ghostErrors, errors);
-module.exports.GhostError = GhostError;
+module.exports = ghostErrors;
+module.exports.utils = {
+    serialize: utils.serialize.bind(ghostErrors),
+    deserialize: utils.deserialize.bind(ghostErrors),
+    isGhostError: utils.isGhostError.bind(ghostErrors)
+};

package/lib/utils.js

@@ -0,0 +1,200 @@
+const omit = require('lodash/omit');
+const merge = require('lodash/merge');
+const extend = require('lodash/extend');
+const _private = {};
+
+_private.serialize = function serialize(err) {
+    try {
+        return {
+            id: err.id,
+            status: err.statusCode,
+            code: err.code || err.errorType,
+            title: err.name,
+            detail: err.message,
+            meta: {
+                context: err.context,
+                help: err.help,
+                errorDetails: err.errorDetails,
+                level: err.level,
+                errorType: err.errorType
+            }
+        };
+    } catch (error) {
+        return {
+            detail: 'Something went wrong.'
+        };
+    }
+};
+
+_private.deserialize = function deserialize(obj) {
+    try {
+        return {
+            id: obj.id,
+            message: obj.detail || obj.error_description || obj.message,
+            statusCode: obj.status,
+            code: obj.code || obj.error,
+            level: obj.meta && obj.meta.level,
+            help: obj.meta && obj.meta.help,
+            context: obj.meta && obj.meta.context
+        };
+    } catch (err) {
+        return {
+            message: 'Something went wrong.'
+        };
+    }
+};
+
+/**
+ * @description Serialize error instance into oauth format.
+ *
+ * @see https://tools.ietf.org/html/rfc6749#page-45
+ *
+ * To not loose any error data when sending errors between internal services, we use the suggested OAuth properties and add ours as well.
+ */
+_private.OAuthSerialize = function OAuthSerialize(err) {
+    const matchTable = {};
+
+    matchTable[this.NoPermissionError.name] = 'access_denied';
+    matchTable[this.MaintenanceError.name] = 'temporarily_unavailable';
+    matchTable[this.BadRequestError.name] = matchTable[this.ValidationError.name] = 'invalid_request';
+    matchTable.default = 'server_error';
+
+    return merge({
+        error: err.code || matchTable[err.name] || 'server_error',
+        error_description: err.message
+    }, omit(_private.serialize(err), ['detail', 'code']));
+};
+
+/**
+ * @description Deserialize oauth error format into GhostError instance.
+ * @param {Object} errorFormat
+ * @return {Error}
+ * @constructor
+ */
+_private.OAuthDeserialize = function OAuthDeserialize(errorFormat) {
+    try {
+        return new this[errorFormat.title || errorFormat.name || this.InternalServerError.name](_private.deserialize(errorFormat));
+    } catch (err) {
+        // CASE: you receive an OAuth formatted error, but the error prototype is unknown
+        return new this.InternalServerError(extend({
+            errorType: errorFormat.title || errorFormat.name
+        }, _private.deserialize(errorFormat)));
+    }
+};
+
+/**
+ * @description Serialize GhostError instance into jsonapi.org format.
+ * @param {Error} err
+ * @return {Object}
+ */
+_private.JSONAPISerialize = function JSONAPISerialize(err) {
+    const errorFormat = {
+        errors: [_private.serialize(err)]
+    };
+
+    errorFormat.errors[0].source = {};
+
+    if (err.property) {
+        errorFormat.errors[0].source.pointer = '/data/attributes/' + err.property;
+    }
+
+    return errorFormat;
+};
+
+/**
+ * @description Deserialize JSON api format into GhostError instance.
+ * @param {Object} errorFormat
+ * @return {Error}
+ */
+_private.JSONAPIDeserialize = function JSONAPIDeserialize(errorFormat) {
+    errorFormat = errorFormat.errors && errorFormat.errors[0] || {};
+
+    let internalError;
+
+    try {
+        internalError = new this[errorFormat.title || errorFormat.name || this.InternalServerError.name](_private.deserialize(errorFormat));
+    } catch (err) {
+        // CASE: you receive a JSON format error, but the error prototype is unknown
+        internalError = new this.InternalServerError(extend({
+            errorType: errorFormat.title || errorFormat.name
+        }, _private.deserialize(errorFormat)));
+    }
+
+    if (errorFormat.source && errorFormat.source.pointer) {
+        internalError.property = errorFormat.source.pointer.split('/')[3];
+    }
+
+    return internalError;
+};
+
+/**
+ * @description Serialize GhostError instance to error JSON format
+ *
+ * jsonapi.org error format:
+ *
+ *  source: {
+ *      parameter: URL query parameter (no support yet)
+ *      pointer: HTTP body attribute
+ *  }
+ *
+ * @see http://jsonapi.org/format/#errors
+ *
+ * @param {Error} err
+ * @param {Object} options { format: [String] (jsonapi || oauth) }
+ */
+exports.serialize = function serialize(err, options) {
+    options = options || {format: 'jsonapi'};
+
+    let errorFormat = {};
+
+    try {
+        if (options.format === 'jsonapi') {
+            errorFormat = _private.JSONAPISerialize.bind(this)(err);
+        } else {
+            errorFormat = _private.OAuthSerialize.bind(this)(err);
+        }
+    } catch (error) {
+        errorFormat.message = 'Something went wrong.';
+    }
+
+    // no need to sanitize the undefined values, on response send JSON.stringify get's called
+    return errorFormat;
+};
+
+/**
+ * @description Deserialize from error JSON format to GhostError instance
+ * @param {Object} errorFormat
+ */
+exports.deserialize = function deserialize(errorFormat) {
+    let internalError = {};
+
+    if (errorFormat.errors) {
+        internalError = _private.JSONAPIDeserialize.bind(this)(errorFormat);
+    } else {
+        internalError = _private.OAuthDeserialize.bind(this)(errorFormat);
+    }
+
+    return internalError;
+};
+
+/**
+ * @description Check whether an error instance is a GhostError.
+ */
+exports.isGhostError = function isGhostError(err) {
+    const errorName = this.GhostError.name;
+
+    const recursiveIsGhostError = function recursiveIsGhostError(obj) {
+        // no super constructor available anymore
+        if (!obj || !obj.name) {
+            return false;
+        }
+
+        if (obj.name === errorName) {
+            return true;
+        }
+
+        return recursiveIsGhostError(Object.getPrototypeOf(obj));
+    };
+
+    return recursiveIsGhostError(err.constructor);
+};

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@tryghost/errors",
-  "version": "0.2.14",
-  "repository": "https://github.com/TryGhost/Utils/tree/master/packages/errors",
+  "version": "1.0.0",
+  "repository": "https://github.com/TryGhost/Utils/tree/main/packages/errors",
   "author": "Ghost Foundation",
   "license": "MIT",
   "main": "index.js",
   "scripts": {
     "dev": "echo \"Implement me!\"",
-    "test": "NODE_ENV=testing c8 mocha './test/**/*.test.js'",
+    "test": "NODE_ENV=testing c8 --reporter text --reporter cobertura mocha './test/**/*.test.js'",
     "lint": "eslint . --ext .js --cache",
     "posttest": "yarn lint"
   },
@@ -19,14 +19,13 @@
     "access": "public"
   },
   "devDependencies": {
-    "c8": "7.9.0",
-    "mocha": "9.0.0",
+    "c8": "7.10.0",
+    "mocha": "9.1.3",
     "should": "13.2.3",
-    "sinon": "11.0.0"
+    "sinon": "11.1.2"
   },
   "dependencies": {
-    "@tryghost/ignition-errors": "^0.1.0",
     "lodash": "^4.17.21"
   },
-  "gitHead": "9545d13a14c1b0ac70cd80ee111f66f642eb0a4d"
+  "gitHead": "9cce0db03f9229f7829ad2d0119b4916ca44fc78"
 }