Add a final error handler package

[rowanmanning]

Add a final error handling package which outputs the error status code, any headers that need to be set, and a basic text-based error page which is intended to be overridden by next-errors.

What problem does this feature solve?

We currently maintain code to output final error information within n-express. At time of writing, it looks like this:

this.app.use((err, req, res, next) => {
	let statusCode = parseInt(err.statusCode || err.status || 500, 10);

	// There's clearly an error, so if the error has a status
	// code of less than `400` we should default to `500` to
	// ensure bad error handling doesn't send false positive
	// status codes. We also check that the status code is
	// a valid number.
	const isValidErrorStatus = (
		!Number.isNaN(statusCode) && // Possible if `error.status` is something unexpected, like an object
		statusCode >= 400 &&
		statusCode <= 599
	);

	res.statusCode = isValidErrorStatus ? statusCode : 500;
	const statusMessage = STATUS_CODES[res.statusCode] || STATUS_CODES[500];

	// If headers have been sent already then we need to hand off to
	// the final Express error handler as documented here:
	// https://expressjs.com/en/guide/error-handling.html#the-default-error-handler
	//
	// This ensures that the app doesn't crash with `ERR_STREAM_WRITE_AFTER_END`
	if (res.headersSent) {
		nLogger.warn({
			event: 'EXPRESS_ERROR_HANDLER_FAILURE',
			message: 'The default n-express error handler could not output because the response has already been sent',
			error: serializeError(err),
			request: serializeRequest(req)
		});
		return next(err);
	}

	// If Sentry is in use, the error id is attached to `res.sentry`
	// to be returned and optionally displayed to the user for support.
	// If Sentry is disabled we fall back to the relevant HTTP status
	// code and message
	const nonSentryOutput = `${res.statusCode} ${statusMessage}`;
	const output = `${appOptions.withSentry ? res.sentry : nonSentryOutput}\n`;
	res.end(output);
});

This is a lot of code maintained outside of Reliability Kit with a focus on errors and how they get presented. We (the CP Reliability team) were the last people who made any changes to this code too.

It's difficult for us to own one part of one file within n-express, n-express does too much anyway, and this doesn't align with our ethos of "trust our engineers" – there's not an easy way to remove this error handling or configure it to suit your app, and it's hidden away in some n-express magic rather than being explicitly included.

Ideal solution

I think we should review what we need from this error rendering middleware and provide a new Reliability Kit package which does this instead. Unsure what it'd be called yet. It feels separate to #227 as we'd be moving existing functionality into Reliability Kit.

Alternatives

We could do nothing and keep this code in n-express, optionally trying to add us as owners of this file. I think we miss an opportunity to reduce the footprint and complexity of n-express though and hand some control back to our teams.

We could also release this package in Reliability Kit and import it into n-express in place of the custom code that'd currently maintained there.

[rowanmanning]

Note: I don't think we should do this until Sentry has been removed from n-express fully, which will be a later major breaking version. Trying to move this code out right now will result in some unnecessary Sentry-related stuff being codified in Reliability Kit

[rowanmanning]

To add some firmer dates, we should be able to do this work after mid-August 2023. At this point we'll be fully removing Sentry from n-express

[rowanmanning]

This work is complete and made it into [email protected]