feat(apollo-engine-reporting) Introduce rewriteError to munge errors for reporting.

[abernix]

This PR supersedes @lpgera's #1639 by building upon the idea and foundation which that PR started.

Not to be confused with the top-level formatError function — which re-shapes the error response that is sent to the client — this newly-introduced rewriteError handler can be defined within the engine settings and used to modify or discard reporting errors to Apollo Engine.

It will receive the err as the first argument and can modify the message property of that error as it sees fit, including returning a new GraphQLError entirely, if desired.

To avoid reporting a particular error, an explicit null may be returned, rather than the error. This will cause the error to never be sent to Apollo Engine and is helpful for lower-severity errors caused by users like apollo-server-errors's AuthenticationErrors which may not make sense to flag as problematic within Apollo Engine.

Note: To avoid inadvertent mistakes, either an error that is an instanceof GraphQLError or an explicit null must be returned. Returning undefined is not permitted.

Avoid reporting lower-severity apollo-server-errors errors.

For example, if the current server is throwing the AuthenticationError provided by apollo-server-errors when a mis-typed password is supplied, an implementor might avoid reporting this to Apollo Engine (and potentially burying higher-severity errors) by defining this as:

const { AuthenticationError } = require("apollo-server-errors");
const server = new ApolloServer({
  typeDefs,  // (Not defined in this example)
  resolvers, //    "      "      "     "
  engine: {
    rewriteError(err) {
      // Return `null` to avoid reporting `AuthenticationError`s
      if (err instanceof AuthenticationError) {
        return null;
      }

      // All other errors will be reported.
      return err;
    }
  },
});

Avoid reporting an error based on other attributes.

const server = new ApolloServer({
  typeDefs,  // (Not defined in this example)
  resolvers, //    "      "      "     "
  engine: {
    rewriteError(err) {
      // Generally, using a more stable property, like `code`, would be
      // preferable to checking the `message` property, but it can be done!
      if (err.message && err.message.match(/^Known error message/) {
        return null;
      }

      // All other errors should still be reported!
      return err;
    }
  },
});

Redacting the error message.

If it is necessary to change the error prior to reporting it to Apollo Engine – for example, if there is personally identifiable information in the error message — the rewriteError function can also help:

const server = new ApolloServer({
  typeDefs,  // (Not defined in this example)
  resolvers, //    "      "      "     "
  engine: {
    rewriteError(err) {
      // Make sure that a specific pattern is removed from all error messages.
      err.message = err.message.replace(/x-api-key:[A-Z0-9-]+/, "REDACTED");
      return err;
    }
  },
});

TODO

• Documentation (See also Update docs for rewriteError. #2585)