fix: gracefully handle state handler errors (#1585)

Previously, when an error was thrown in a state handler
an HTTP 500 was sent back to the core engine, making it hard
to debug the issue from within test frameworks.

This change wraps the state handlers with error
handling, rather than propagating the error back
to the pact core engine. Errors will be clearly printed
to the console (and logged at ERROR level).

Fixes #631

Co-authored-by: mefellows <mefellows@users.noreply.github.com>

Author: mefellows

package-lock.json

@@ -116,7 +116,8 @@
     "lodash": "^4.17.21",
     "ramda": "^0.32.0",
     "randexp": "^0.5.3",
-    "router": "^2.2.0"
+    "router": "^2.2.0",
+    "stack-utils": "^2.0.6"
   },
   "devDependencies": {
     "@babel/cli": "7.28.3",
@@ -134,6 +135,7 @@
     "@types/ramda": "0.31.1",
     "@types/sinon": "17.0.4",
     "@types/sinon-chai": "4.0.0",
+    "@types/stack-utils": "^2.0.3",
     "@typescript-eslint/eslint-plugin": "5.62.0",
     "@typescript-eslint/parser": "5.62.0",
     "chai": "6.2.0",

package.json

@@ -3,6 +3,7 @@ import chaiAsPromised from 'chai-as-promised';
 
 import express from 'express';
 
+import sinon from 'sinon';
 import { createProxyStateHandler } from './stateHandler';
 import { ProxyOptions, StateHandlers } from '../types';
 
@@ -54,7 +55,8 @@ describe('#createProxyStateHandler', () => {
       },
     };
 
-    it('returns a 500', async () => {
+    it('returns a 200 and logs an error', async () => {
+      const spy = sinon.spy(console, 'log');
       const h = createProxyStateHandler({
         stateHandlers: badStateHandlers,
       } as ProxyOptions);
@@ -65,7 +67,11 @@ describe('#createProxyStateHandler', () => {
         mockResponse as express.Response
       );
 
-      expect(res).to.eql(500);
+      expect(res).to.eql(200);
+      expect(spy.callCount).to.eql(3);
+      expect(spy.getCall(0).args[0]).to.include(
+        "Error executing state handler for state 'thing exists' on 'setup'."
+      );
     });
   });
 });

src/dsl/verifier/proxy/stateHandler/stateHandler.spec.ts

@@ -1,14 +1,43 @@
 import express from 'express';
 
+import StackUtils from 'stack-utils';
+import chalk from 'chalk';
 import { ProxyOptions, ProviderState } from '../types';
 import { setupStates } from './setupStates';
 
+const cleanStack = (e: Error) => {
+  const stack = new StackUtils({
+    cwd: process.cwd(),
+    internals: StackUtils.nodeInternals(),
+  });
+
+  if (!e.stack) return '';
+  const cleanedStack = stack.clean(e.stack);
+  const lines = cleanedStack.split('\n').map((line) => line.trim());
+
+  return lines[0];
+};
+
 export const createProxyStateHandler =
   (config: ProxyOptions) =>
-  (req: express.Request, res: express.Response): Promise<express.Response> => {
-    const message: ProviderState = req.body;
+  async (
+    req: express.Request,
+    res: express.Response
+  ): Promise<express.Response> => {
+    const state: ProviderState = req.body;
+    try {
+      const data = await setupStates(state, config);
+      return res.json(data);
+    } catch (e) {
+      const error = `\nError executing state handler for state '${state.state}' on '${state.action}'.`;
+      const errorDetails = `↳ Error details: ${e.message}`;
+      const errorSource = `↳ Error source: ${cleanStack(e)}\n`;
+      /* eslint-disable no-console */
+      console.log(chalk.red(error));
+      console.log(chalk.red(errorDetails));
+      console.log(chalk.red(errorSource));
+      /* eslint-enable */
 
-    return Promise.resolve(setupStates(message, config))
-      .then((data) => res.json(data))
-      .catch((e) => res.status(500).send(e));
+      return res.status(200).send();
+    }
   };