feat(stepfunctions): properties for ErrorPath, CausePath, MaxDelay, Jitter (#27051)

The Fail state supports JsonPath values in the `ErrorPath` and `CausePath` field to filter the state input and serve as the state error and cause.

The Retry block supports exponential backoff with Jitter and capped interval retry growth with MaxDelay. 

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: kaizencc

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

@@ -128,6 +128,8 @@ These properties impact how each individual step interacts with the state machin
 * `resultSelector`: the part of the step result that should be added to the state machine data
 * `resultPath`: where in the state machine data the step result should be inserted
 * `outputPath`: what part of the state machine data should be retained
+* `errorPath`: the part of the data object that gets returned as the step error
+* `causePath`: the part of the data object that gets returned as the step cause
 
 Their values should be a string indicating a [JSON path](https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-paths.html) into the State Machine Data object (like `"$.MyKey"`). If absent, the values are treated as if they were `"$"`, which means the entire object.
 
@@ -421,8 +423,12 @@ parallel.branch(shipItem);
 parallel.branch(sendInvoice);
 parallel.branch(restock);
 
-// Retry the whole workflow if something goes wrong
-parallel.addRetry({ maxAttempts: 1 });
+// Retry the whole workflow if something goes wrong with exponential backoff
+parallel.addRetry({
+  maxAttempts: 1,
+  maxDelay: Duration.seconds(5),
+  jitterStrategy: sfn.JitterType.FULL,
+});
 
 // How to recover from errors
 const sendFailureNotification = new sfn.Pass(this, 'SendFailureNotification');
@@ -449,12 +455,21 @@ failure status. The fail state should report the reason for the failure.
 Failures can be caught by encompassing `Parallel` states.
 
 ```ts
-const success = new sfn.Fail(this, 'Fail', {
+const fail = new sfn.Fail(this, 'Fail', {
   error: 'WorkflowFailure',
   cause: "Something went wrong",
 });
 ```
 
+The `Fail` state also supports returning dynamic values as the error and cause that are selected from the input with a path.
+
+```ts
+const fail = new sfn.Fail(this, 'Fail', {
+  errorPath: sfn.JsonPath.stringAt('$.someError'),
+  causePath: sfn.JsonPath.stringAt('$.someCause'),
+});
+```
+
 ### Map
 
 A `Map` state can be used to run a set of steps for each element of an input array.
@@ -961,12 +976,12 @@ const stack = new Stack(app, 'MyStack');
 sfn.StateMachine.fromStateMachineArn(
   this,
   "ViaArnImportedStateMachine",
-  "arn:aws:states:us-east-1:123456789012:stateMachine:StateMachine2E01A3A5-N5TJppzoevKQ"
+  "arn:aws:states:us-east-1:123456789012:stateMachine:StateMachine2E01A3A5-N5TJppzoevKQ",
 );
 
 sfn.StateMachine.fromStateMachineName(
   this,
   "ViaResourceNameImportedStateMachine",
-  "StateMachine2E01A3A5-N5TJppzoevKQ"
+  "StateMachine2E01A3A5-N5TJppzoevKQ",
 );
 ```

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

@@ -1,6 +1,6 @@
 import { Construct } from 'constructs';
 import { StateType } from './private/state-type';
-import { State } from './state';
+import { renderJsonPath, State } from './state';
 import { INextable } from '../types';
 
 /**
@@ -10,23 +10,37 @@ export interface FailProps {
   /**
    * An optional description for this state
    *
-   * @default No comment
+   * @default - No comment
    */
   readonly comment?: string;
 
   /**
    * Error code used to represent this failure
    *
-   * @default No error code
+   * @default - No error code
    */
   readonly error?: string;
 
+  /**
+   * JsonPath expression to select part of the state to be the error to this state.
+   *
+   * @default - No error path
+   */
+  readonly errorPath?: string;
+
   /**
    * A description for the cause of the failure
    *
-   * @default No description
+   * @default - No description
    */
   readonly cause?: string;
+
+  /**
+   * JsonPath expression to select part of the state to be the cause to this state.
+   *
+   * @default - No cause path
+   */
+  readonly causePath?: string;
 }
 
 /**
@@ -38,13 +52,17 @@ export class Fail extends State {
   public readonly endStates: INextable[] = [];
 
   private readonly error?: string;
+  private readonly errorPath?: string;
   private readonly cause?: string;
+  private readonly causePath?: string;
 
   constructor(scope: Construct, id: string, props: FailProps = {}) {
     super(scope, id, props);
 
     this.error = props.error;
+    this.errorPath = props.errorPath;
     this.cause = props.cause;
+    this.causePath = props.causePath;
   }
 
   /**
@@ -55,7 +73,9 @@ export class Fail extends State {
       Type: StateType.FAIL,
       Comment: this.comment,
       Error: this.error,
+      ErrorPath: renderJsonPath(this.errorPath),
       Cause: this.cause,
+      CausePath: renderJsonPath(this.causePath),
     };
   }
-}
+}

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

@@ -525,6 +525,8 @@ function renderRetry(retry: RetryProps) {
     IntervalSeconds: retry.interval && retry.interval.toSeconds(),
     MaxAttempts: retry.maxAttempts,
     BackoffRate: retry.backoffRate,
+    MaxDelaySeconds: retry.maxDelay && retry.maxDelay.toSeconds(),
+    JitterStrategy: retry.jitterStrategy,
   };
 }
 

packages/aws-cdk-lib/aws-stepfunctions/lib/types.ts

@@ -34,6 +34,21 @@ export interface IChainable {
   readonly endStates: INextable[];
 }
 
+/**
+ * Values allowed in the retrier JitterStrategy field
+ */
+export enum JitterType {
+  /**
+   * Calculates the delay to be a random number between 0 and the computed backoff for the given retry attempt count
+   */
+  FULL = 'FULL',
+
+  /**
+   * Calculates the delay to be the computed backoff for the given retry attempt count (equivalent to if Jitter was not declared - i.e. the default value)
+   */
+  NONE = 'NONE',
+}
+
 /**
  * Predefined error strings
  * Error names in Amazon States Language - https://states-language.net/spec.html#appendix-a
@@ -121,6 +136,20 @@ export interface RetryProps {
    */
   readonly maxAttempts?: number;
 
+  /**
+   * Maximum limit on retry interval growth during exponential backoff.
+   *
+   * @default - No max delay
+   */
+  readonly maxDelay?: Duration;
+
+  /**
+   * Introduces a randomization over the retry interval.
+   *
+   * @default - No jitter strategy
+   */
+  readonly jitterStrategy?: JitterType;
+
   /**
    * Multiplication for how much longer the wait interval gets on every retry
    *
@@ -158,4 +187,4 @@ export interface CatchProps {
  * Special string value to discard state input, output or result
  * @deprecated use JsonPath.DISCARD
  */
-export const DISCARD = 'DISCARD';
+export const DISCARD = 'DISCARD';

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

@@ -77,6 +77,25 @@ describe('State Machine Resources', () => {
     });
   }),
 
+  test('Fail should render ErrorPath / CausePath correctly', () => {
+    // GIVEN
+    const stack = new cdk.Stack();
+    const fail = new stepfunctions.Fail(stack, 'Fail', {
+      errorPath: stepfunctions.JsonPath.stringAt('$.error'),
+      causePath: stepfunctions.JsonPath.stringAt('$.cause'),
+    });
+
+    // WHEN
+    const failState = stack.resolve(fail.toStateJson());
+
+    // THEN
+    expect(failState).toStrictEqual({
+      CausePath: '$.cause',
+      ErrorPath: '$.error',
+      Type: 'Fail',
+    });
+  }),
+
   testDeprecated('Task should render InputPath / Parameters / OutputPath correctly', () => {
     // GIVEN
     const stack = new cdk.Stack();

packages/aws-cdk-lib/aws-stepfunctions/test/task-base.test.ts

@@ -229,8 +229,12 @@ describe('Task base', () => {
 
   test('add retry configuration', () => {
     // WHEN
-    task.addRetry({ errors: ['HTTPError'], maxAttempts: 2 })
-      .addRetry(); // adds default retry
+    task.addRetry({
+      errors: ['HTTPError'],
+      maxAttempts: 2,
+      maxDelay: cdk.Duration.seconds(10),
+      jitterStrategy: sfn.JitterType.FULL,
+    }).addRetry();
 
     // THEN
     expect(renderGraph(task)).toEqual({
@@ -242,6 +246,8 @@ describe('Task base', () => {
             {
               ErrorEquals: ['HTTPError'],
               MaxAttempts: 2,
+              MaxDelaySeconds: 10,
+              JitterStrategy: 'FULL',
             },
             {
               ErrorEquals: ['States.ALL'],