@tryghost/errors 1.2.26 → 1.3.0

package/src/GhostError.ts

@@ -0,0 +1,96 @@
+import {v1 as uuidv1} from 'uuid';
+import {wrapStack} from './wrap-stack';
+
+export interface GhostErrorOptions {
+    message?: string;
+    statusCode?: number;
+    level?: string;
+    id?: string;
+    context?: string;
+    help?: string;
+    errorType?: string;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    errorDetails?: any;
+    code?: string;
+    property?: string;
+    redirect?: string;
+    hideStack?: boolean;
+    err?: Error | string;
+}
+
+export class GhostError extends Error {
+    statusCode: number;
+    errorType: string;
+    level: string;
+    id: string;
+    context?: string;
+    help?: string;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    errorDetails: any;
+    code: string | null;
+    property: string | null;
+    redirect: string | null;
+    hideStack: boolean;
+
+    constructor(options: GhostErrorOptions = {}) {
+        super();
+
+        /**
+         * defaults
+         */
+        this.statusCode = 500;
+        this.errorType = 'InternalServerError';
+        this.level = 'normal';
+        this.message = 'The server has encountered an error.';
+        this.id = uuidv1();
+
+        /**
+         * 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.help = options.help;
+        this.errorType = this.name = options.errorType || this.errorType;
+        this.errorDetails = options.errorDetails;
+        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 || false;
+
+        // 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 (typeof options.err === 'string') {
+                /* 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') {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    this[property] = this[property] || (options.err as any)[property];
+                    return;
+                }
+
+                if (property === 'stack' && !this.hideStack) {
+                    this[property] = wrapStack(this, options.err as Error);
+                    return;
+                }
+
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                (this as any)[property] = (options.err as any)[property] || (this as any)[property];
+            });
+        }
+    }
+}

package/src/errors.ts

@@ -0,0 +1,301 @@
+import {GhostError, GhostErrorOptions} from './GhostError';
+
+const mergeOptions = (options: GhostErrorOptions, defaults: GhostErrorOptions) => {
+    const result = {...defaults};
+
+    // Ignore undefined options - for example passing statusCode: undefined should not override the default
+    (Object.keys(options) as (keyof GhostErrorOptions)[]).forEach((key) => {
+        if (options[key] !== undefined) {
+            result[key] = options[key];
+        }
+    });
+
+    return result;
+};
+
+export class InternalServerError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 500,
+            level: 'critical',
+            errorType: 'InternalServerError',
+            message: 'The server has encountered an error.'
+        }));
+    }
+}
+
+export class IncorrectUsageError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 400,
+            level: 'critical',
+            errorType: 'IncorrectUsageError',
+            message: 'We detected a misuse. Please read the stack trace.'
+        }));
+    }
+}
+
+export class NotFoundError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 404,
+            errorType: 'NotFoundError',
+            message: 'Resource could not be found.',
+            hideStack: true
+        }));
+    }
+}
+
+export class BadRequestError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 400,
+            errorType: 'BadRequestError',
+            message: 'The request could not be understood.'
+        }));
+    }
+}
+
+export class UnauthorizedError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 401,
+            errorType: 'UnauthorizedError',
+            message: 'You are not authorised to make this request.'
+        }));
+    }
+}
+
+export class NoPermissionError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 403,
+            errorType: 'NoPermissionError',
+            message: 'You do not have permission to perform this request.'
+        }));
+    }
+}
+
+export class ValidationError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 422,
+            errorType: 'ValidationError',
+            message: 'The request failed validation.'
+        }));
+    }
+}
+
+export class UnsupportedMediaTypeError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 415,
+            errorType: 'UnsupportedMediaTypeError',
+            message: 'The media in the request is not supported by the server.'
+        }));
+    }
+}
+
+export class TooManyRequestsError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 429,
+            errorType: 'TooManyRequestsError',
+            message: 'Server has received too many similar requests in a short space of time.'
+        }));
+    }
+}
+
+export class MaintenanceError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 503,
+            errorType: 'MaintenanceError',
+            message: 'The server is temporarily down for maintenance.'
+        }));
+    }
+}
+
+export class MethodNotAllowedError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 405,
+            errorType: 'MethodNotAllowedError',
+            message: 'Method not allowed for resource.'
+        }));
+    }
+}
+
+export class RequestNotAcceptableError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 406,
+            errorType: 'RequestNotAcceptableError',
+            message: 'Request not acceptable for provided Accept-Version header.',
+            hideStack: true
+        }));
+    }
+}
+
+export class RequestEntityTooLargeError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 413,
+            errorType: 'RequestEntityTooLargeError',
+            message: 'Request was too big for the server to handle.'
+        }));
+    }
+}
+
+export class TokenRevocationError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 503,
+            errorType: 'TokenRevocationError',
+            message: 'Token is no longer available.'
+        }));
+    }
+}
+
+export class VersionMismatchError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 400,
+            errorType: 'VersionMismatchError',
+            message: 'Requested version does not match server version.'
+        }));
+    }
+}
+
+export class DataExportError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 500,
+            errorType: 'DataExportError',
+            message: 'The server encountered an error whilst exporting data.'
+        }));
+    }
+}
+
+export class DataImportError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 500,
+            errorType: 'DataImportError',
+            message: 'The server encountered an error whilst importing data.'
+        }));
+    }
+}
+
+export class EmailError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 500,
+            errorType: 'EmailError',
+            message: 'The server encountered an error whilst sending email.'
+        }));
+    }
+}
+
+export class ThemeValidationError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 422,
+            errorType: 'ThemeValidationError',
+            message: 'The theme has a validation error.',
+            errorDetails: {}
+        }));
+    }
+}
+
+export class DisabledFeatureError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 409,
+            errorType: 'DisabledFeatureError',
+            message: 'Unable to complete the request, this feature is disabled.'
+        }));
+    }
+}
+
+export class UpdateCollisionError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            statusCode: 409,
+            errorType: 'UpdateCollisionError',
+            message: 'Unable to complete the request, there was a conflict.'
+        }));
+    }
+}
+
+export class HostLimitError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            errorType: 'HostLimitError',
+            hideStack: true,
+            statusCode: 403,
+            message: 'Unable to complete the request, this resource is limited.'
+        }));
+    }
+}
+
+export class HelperWarning extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            errorType: 'HelperWarning',
+            hideStack: true,
+            statusCode: 400,
+            message: 'A theme helper has done something unexpected.'
+        }));
+    }
+}
+
+export class PasswordResetRequiredError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            errorType: 'PasswordResetRequiredError',
+            statusCode: 401,
+            message: 'For security, you need to create a new password. An email has been sent to you with instructions!'
+        }));
+    }
+}
+
+export class UnhandledJobError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            errorType: 'UnhandledJobError',
+            message: 'Processed job threw an unhandled error',
+            level: 'critical'
+        }));
+    }
+}
+
+export class NoContentError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            errorType: 'NoContentError',
+            statusCode: 204,
+            hideStack: true
+        }));
+    }
+}
+
+export class ConflictError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            errorType: 'ConflictError',
+            statusCode: 409,
+            message: 'The server has encountered an conflict.'
+        }));
+    }
+}
+
+export class MigrationError extends GhostError {
+    constructor(options: GhostErrorOptions = {}) {
+        super(mergeOptions(options, {
+            errorType: 'MigrationError',
+            message: 'An error has occurred applying a database migration.',
+            level: 'critical'
+        }));
+    }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+import {GhostError} from './GhostError';
+import * as ghostErrors from './errors';
+import {deserialize, isGhostError, prepareStackForUser, serialize} from './utils';
+
+export * from './errors';
+export type {GhostError};
+export default ghostErrors;
+
+export const utils = {
+    serialize,
+    deserialize,
+    isGhostError,
+    prepareStackForUser
+};

package/src/utils.ts

@@ -0,0 +1,238 @@
+import deepCopy from '@stdlib/utils-copy';
+import {GhostError} from './GhostError';
+import * as errors from './errors';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyObject = Record<string, any>
+
+const errorsWithBase: Record<string, typeof GhostError> = {...errors, GhostError};
+
+const _private = {
+    serialize(err: GhostError) {
+        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.'
+            };
+        }
+    },
+
+    deserialize(obj: AnyObject) {
+        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
+        };
+    },
+
+    /**
+     * @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.
+     */
+    OAuthSerialize(err: GhostError) {
+        const matchTable = {
+            [errors.NoPermissionError.name]: 'access_denied',
+            [errors.MaintenanceError.name]: 'temporarily_unavailable',
+            [errors.BadRequestError.name]: 'invalid_request',
+            [errors.ValidationError.name]: 'invalid_request',
+            default: 'server_error'
+        };
+
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const {detail, code, ...properties} = _private.serialize(err);
+
+        return {
+            error: err.code || matchTable[err.name] || 'server_error',
+            error_description: err.message,
+            ...properties
+        };
+    },
+
+    /**
+     * @description Deserialize oauth error format into GhostError instance.
+     * @constructor
+     */
+    OAuthDeserialize(errorFormat: AnyObject): GhostError {
+        try {
+            return new errorsWithBase[errorFormat.title || errorFormat.name || errors.InternalServerError.name](_private.deserialize(errorFormat));
+        } catch (err) {
+            // CASE: you receive an OAuth formatted error, but the error prototype is unknown
+            return new errors.InternalServerError({
+                errorType: errorFormat.title || errorFormat.name,
+                ..._private.deserialize(errorFormat)
+            });
+        }
+    },
+
+    /**
+     * @description Serialize GhostError instance into jsonapi.org format.
+     * @param err
+     * @return {Object}
+     */
+    JSONAPISerialize(err: GhostError): AnyObject {
+        const errorFormat: AnyObject = {
+            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.
+     */
+    JSONAPIDeserialize(errorFormat: AnyObject): GhostError {
+        errorFormat = errorFormat.errors && errorFormat.errors[0] || {};
+
+        let internalError;
+
+        try {
+            internalError = new errorsWithBase[errorFormat.title || errorFormat.name || errors.InternalServerError.name](_private.deserialize(errorFormat));
+        } catch (err) {
+            // CASE: you receive a JSON format error, but the error prototype is unknown
+            internalError = new errors.InternalServerError({
+                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
+ */
+export function serialize(err: GhostError, options?: {format: 'jsonapi' | 'oauth'}) {
+    options = options || {format: 'jsonapi'};
+
+    let errorFormat: AnyObject = {};
+
+    try {
+        if (options.format === 'jsonapi') {
+            errorFormat = _private.JSONAPISerialize(err);
+        } else {
+            errorFormat = _private.OAuthSerialize(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
+ */
+export function deserialize(errorFormat: AnyObject): AnyObject {
+    let internalError = {};
+
+    if (errorFormat.errors) {
+        internalError = _private.JSONAPIDeserialize(errorFormat);
+    } else {
+        internalError = _private.OAuthDeserialize(errorFormat);
+    }
+
+    return internalError;
+};
+
+/**
+ * @description Replace the stack with a user-facing one
+ * @returns Clone of the original error with a user-facing stack
+ */
+export function prepareStackForUser(error: GhostError): GhostError
+export function prepareStackForUser(error: Error): Error
+export function prepareStackForUser(error: Error): Error {
+    const stackbits = error.stack?.split(/\n/) || [];
+
+    // We build this up backwards, so we always insert at position 1
+
+    const hideStack = 'hideStack' in error && error.hideStack;
+
+    if (process.env.NODE_ENV === 'production' || hideStack) {
+        stackbits.splice(1, stackbits.length - 1);
+    } else {
+        // Clearly mark the strack trace
+        stackbits.splice(1, 0, `Stack Trace:`);
+    }
+
+    // Add in our custom context and help methods
+    if ('help' in error && error.help) {
+        stackbits.splice(1, 0, `${error.help}`);
+    }
+
+    if ('context' in error && error.context) {
+        stackbits.splice(1, 0, `${error.context}`);
+    }
+
+    // @NOTE: would be a good idea to swap out the cloning implementation with native
+    //        `structuredClone` one once we use Node v17 or higher. Before making an
+    //        upgrade make sure structuredClone does a full copy of all properties
+    //        present on a custom error (see issue: https://github.com/ungap/structured-clone/issues/12)
+    const errorClone = deepCopy(error);
+    errorClone.stack = stackbits.join('\n');
+    return errorClone;
+};
+
+/**
+ * @description Check whether an error instance is a GhostError.
+ */
+export function isGhostError(err: Error) {
+    const errorName = GhostError.name;
+    const legacyErrorName = 'IgnitionError';
+
+    const recursiveIsGhostError = function recursiveIsGhostError(obj: AnyObject): boolean {
+        // no super constructor available anymore
+        if (!obj || !obj.name) {
+            return false;
+        }
+
+        if (obj.name === errorName || obj.name === legacyErrorName) {
+            return true;
+        }
+
+        return recursiveIsGhostError(Object.getPrototypeOf(obj));
+    };
+
+    return recursiveIsGhostError(err.constructor);
+};

package/src/wrap-stack.ts

@@ -0,0 +1,5 @@
+export function wrapStack(err: Error, internalErr: Error) {
+    const extraLine = (err.stack?.split(/\n/g) || [])[1];
+    const [firstLine, ...rest] = internalErr.stack?.split(/\n/g) || [];
+    return [firstLine, extraLine, ...rest].join('\n');
+};

package/types/GhostError.d.ts

@@ -0,0 +1,30 @@
+export interface GhostErrorOptions {
+    message?: string;
+    statusCode?: number;
+    level?: string;
+    id?: string;
+    context?: string;
+    help?: string;
+    errorType?: string;
+    errorDetails?: any;
+    code?: string;
+    property?: string;
+    redirect?: string;
+    hideStack?: boolean;
+    err?: Error | string;
+}
+export declare class GhostError extends Error {
+    statusCode: number;
+    errorType: string;
+    level: string;
+    id: string;
+    context?: string;
+    help?: string;
+    errorDetails: any;
+    code: string | null;
+    property: string | null;
+    redirect: string | null;
+    hideStack: boolean;
+    constructor(options?: GhostErrorOptions);
+}
+//# sourceMappingURL=GhostError.d.ts.map

package/types/GhostError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GhostError.d.ts","sourceRoot":"","sources":["../src/GhostError.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,iBAAiB;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,YAAY,CAAC,EAAE,GAAG,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CACxB;AAED,qBAAa,UAAW,SAAQ,KAAK;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,YAAY,EAAE,GAAG,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;gBAEP,OAAO,GAAE,iBAAsB;CA6D9C"}