fix(stepfunctions): cannot use intrinsic functions in Fail state

packages/aws-cdk-lib/aws-stepfunctions/README.md

@@ -487,6 +487,16 @@ const fail = new sfn.Fail(this, 'Fail', {
 });
 ```
 
+You can also use an intrinsic function that returns a string to specify CausePath and ErrorPath.
+The available functions include States.Format, States.JsonToString, States.ArrayGetItem, States.Base64Encode, States.Base64Decode, States.Hash, and States.UUID.
+
+```ts
+const fail = new sfn.Fail(this, 'Fail', {
+  errorPath: sfn.JsonPath.format('error: {}.', sfn.JsonPath.stringAt('$.someError')),
+  causePath: "States.Format('cause: {}.', $.someCause)",
+});
+```
+
 ### Map
 
 A `Map` state can be used to run a set of steps for each element of an input array.

packages/aws-cdk-lib/aws-stepfunctions/lib/states/fail.ts

@@ -1,6 +1,7 @@
 import { Construct } from 'constructs';
 import { StateType } from './private/state-type';
 import { renderJsonPath, State } from './state';
+import { Token } from '../../../core';
 import { INextable } from '../types';
 
 /**
@@ -31,6 +32,9 @@ export interface FailProps {
   /**
    * JsonPath expression to select part of the state to be the error to this state.
    *
+   * You can also use an intrinsic function that returns a string to specify this property.
+   * The allowed functions include States.Format, States.JsonToString, States.ArrayGetItem, States.Base64Encode, States.Base64Decode, States.Hash, and States.UUID.
+   *
    * @default - No error path
    */
   readonly errorPath?: string;
@@ -45,6 +49,9 @@ export interface FailProps {
   /**
    * JsonPath expression to select part of the state to be the cause to this state.
    *
+   * You can also use an intrinsic function that returns a string to specify this property.
+   * The allowed functions include States.Format, States.JsonToString, States.ArrayGetItem, States.Base64Encode, States.Base64Decode, States.Hash, and States.UUID.
+   *
    * @default - No cause path
    */
   readonly causePath?: string;
@@ -56,6 +63,16 @@ export interface FailProps {
  * Reaching a Fail state terminates the state execution in failure.
  */
 export class Fail extends State {
+  private static allowedIntrinsics = [
+    'States.Format',
+    'States.JsonToString',
+    'States.ArrayGetItem',
+    'States.Base64Encode',
+    'States.Base64Decode',
+    'States.Hash',
+    'States.UUID',
+  ];
+
   public readonly endStates: INextable[] = [];
 
   private readonly error?: string;
@@ -80,9 +97,42 @@ export class Fail extends State {
       Type: StateType.FAIL,
       Comment: this.comment,
       Error: this.error,
-      ErrorPath: renderJsonPath(this.errorPath),
+      ErrorPath: this.isIntrinsicString(this.errorPath) ? this.errorPath : renderJsonPath(this.errorPath),
       Cause: this.cause,
-      CausePath: renderJsonPath(this.causePath),
+      CausePath: this.isIntrinsicString(this.causePath) ? this.causePath : renderJsonPath(this.causePath),
     };
   }
-}
+
+  /**
+   * Validate this state
+   */
+  protected validateState(): string[] {
+    const errors = super.validateState();
+
+    if (this.errorPath && this.isIntrinsicString(this.errorPath) && !this.isAllowedIntrinsic(this.errorPath)) {
+      errors.push(`You must specify a valid intrinsic function in errorPath. Must be one of ${Fail.allowedIntrinsics.join(', ')}`);
+    }
+
+    if (this.causePath && this.isIntrinsicString(this.causePath) && !this.isAllowedIntrinsic(this.causePath)) {
+      errors.push(`You must specify a valid intrinsic function in causePath. Must be one of ${Fail.allowedIntrinsics.join(', ')}`);
+    }
+
+    if (this.error && this.errorPath) {
+      errors.push('Fail state cannot have both error and errorPath');
+    }
+
+    if (this.cause && this.causePath) {
+      errors.push('Fail state cannot have both cause and causePath');
+    }
+
+    return errors;
+  }
+
+  private isIntrinsicString(jsonPath?: string): boolean {
+    return !Token.isUnresolved(jsonPath) && !jsonPath?.startsWith('$');
+  }
+
+  private isAllowedIntrinsic(intrinsic: string): boolean {
+    return Fail.allowedIntrinsics.some(allowed => intrinsic.startsWith(allowed));
+  }
+}

packages/aws-cdk-lib/aws-stepfunctions/test/state-machine-resources.test.ts

@@ -96,6 +96,88 @@ describe('State Machine Resources', () => {
     });
   }),
 
+  test.each([
+    [
+      "States.Format('error: {}.', $.error)",
+      "States.Format('cause: {}.', $.cause)",
+    ],
+    [
+      stepfunctions.JsonPath.format('error: {}.', stepfunctions.JsonPath.stringAt('$.error')),
+      stepfunctions.JsonPath.format('cause: {}.', stepfunctions.JsonPath.stringAt('$.cause')),
+    ],
+  ])('Fail should render ErrorPath / CausePath correctly when specifying ErrorPath / CausePath using intrinsics', (errorPath, causePath) => {
+    // GIVEN
+    const app = new cdk.App();
+    const stack = new cdk.Stack(app);
+    const fail = new stepfunctions.Fail(stack, 'Fail', {
+      errorPath,
+      causePath,
+    });
+
+    // WHEN
+    const failState = stack.resolve(fail.toStateJson());
+
+    // THEN
+    expect(failState).toStrictEqual({
+      CausePath: "States.Format('cause: {}.', $.cause)",
+      ErrorPath: "States.Format('error: {}.', $.error)",
+      Type: 'Fail',
+    });
+    expect(() => app.synth()).not.toThrow();
+  }),
+
+  test('fails in synthesis if error and errorPath are defined in Fail state', () => {
+    // GIVEN
+    const app = new cdk.App();
+    const stack = new cdk.Stack(app);
+
+    // WHEN
+    new stepfunctions.Fail(stack, 'Fail', {
+      error: 'error',
+      errorPath: '$.error',
+    });
+
+    expect(() => app.synth()).toThrow(/Fail state cannot have both error and errorPath/);
+  }),
+
+  test('fails in synthesis if cause and causePath are defined in Fail state', () => {
+    // GIVEN
+    const app = new cdk.App();
+    const stack = new cdk.Stack(app);
+
+    // WHEN
+    new stepfunctions.Fail(stack, 'Fail', {
+      cause: 'cause',
+      causePath: '$.cause',
+    });
+
+    expect(() => app.synth()).toThrow(/Fail state cannot have both cause and causePath/);
+  }),
+
+  test.each([
+    'States.Array($.Id)',
+    'States.ArrayPartition($.inputArray, 4)',
+    'States.ArrayContains($.inputArray, $.lookingFor)',
+    'States.ArrayRange(1, 9, 2)',
+    'States.ArrayLength($.inputArray)',
+    'States.JsonMerge($.json1, $.json2, false)',
+    'States.StringToJson($.escapedJsonString)',
+    'plainString',
+  ])('fails in synthesis if specifying invalid intrinsic functions in the causePath and errorPath (%s)', (intrinsic) => {
+    // GIVEN
+    const app = new cdk.App();
+    const stack = new cdk.Stack(app);
+
+    // WHEN
+    new stepfunctions.Fail(stack, 'Fail', {
+      causePath: intrinsic,
+      errorPath: intrinsic,
+    });
+
+    expect(() => app.synth()).toThrow(/You must specify a valid intrinsic function in causePath. Must be one of States.Format, States.JsonToString, States.ArrayGetItem, States.Base64Encode, States.Base64Decode, States.Hash, States.UUID/);
+    expect(() => app.synth()).toThrow(/You must specify a valid intrinsic function in errorPath. Must be one of States.Format, States.JsonToString, States.ArrayGetItem, States.Base64Encode, States.Base64Decode, States.Hash, States.UUID/);
+  }),
+
   testDeprecated('Task should render InputPath / Parameters / OutputPath correctly', () => {
     // GIVEN
     const stack = new cdk.Stack();
@@ -721,7 +803,6 @@ describe('State Machine Resources', () => {
       ],
     });
   });
-
 });
 
 interface FakeTaskProps extends stepfunctions.TaskStateBaseProps {