feat(stepfunctions-tasks): add httpinvoke step functions task

packages/aws-cdk-lib/aws-stepfunctions-tasks/lib/http/invoke.ts

@@ -0,0 +1,129 @@
+import { Construct } from 'constructs';
+import * as iam from '../../../aws-iam';
+import * as sfn from '../../../aws-stepfunctions';
+import { integrationResourceArn } from '../private/task-utils';
+
+export enum URLEncodingArrayFormat {
+  /**
+   * Encode arrays using brackets. For example, {"array": ["a","b","c"]} encodes to "array[]=a&array[]=b&array[]=c"
+   */
+  BRACKETS = 'BRACKETS',
+  /**
+   * Encode arrays using commas. For example, {"array": ["a","b","c"]} encodes to "array=a,b,c,d"
+   */
+  COMMAS = 'COMMAS',
+  /**
+   * Encode arrays using the index value. For example, {"array": ["a","b","c"]} encodes to "array[0]=a&array[1]=b&array[2]=c"
+   */
+  INDICES = 'INDICES',
+  /**
+   * Repeat key for each item in the array. For example, {"array": ["a","b","c"]} encodes to "array[]=a&array[]=b&array[]=c"
+   */
+  REPEAT = 'REPEAT',
+}
+
+/**
+ * Properties for calling an external HTTP endpoint with HttpInvoke.
+ */
+export interface HttpInvokeProps extends sfn.TaskStateBaseProps {
+  /**
+   * The API apiEndpoint to call.
+   */
+  readonly apiEndpoint: string;
+
+  /**
+   * The HTTP method to use.
+   *
+   */
+  readonly method: string;
+
+  /**
+   * The EventBridge Connection ARN to use for authentication.
+   *
+   */
+  readonly connectionArn: string;
+
+  /**
+   * The body to send to the HTTP endpoint.
+   *
+   * @default - No body.
+   */
+  readonly body?: string;
+
+  /**
+   * The headers to send to the HTTP endpoint.
+   *
+   * @default - No headers.
+   */
+  readonly headers?: { [key: string]: string };
+
+  /**
+   * The query string parameters to send to the HTTP endpoint.
+   *
+   * @default - No query string parameters.
+   */
+  readonly queryStringParameters?: { [key: string]: string };
+
+  /**
+   * Whether to URL-encode the request body.
+   * If set to true, also sets 'content-type' header to 'application/x-www-form-urlencoded'
+   *
+   * @default - No encoding.
+   */
+  readonly urlEncodeBody?: boolean;
+
+  /**
+   * The format of the array encoding if urlEncodeBody is set to true.
+   *
+   * @default - ArrayEncodingFormat.INDICES
+   */
+  readonly arrayEncodingFormat?: URLEncodingArrayFormat;
+}
+
+export class HttpInvoke extends sfn.TaskStateBase {
+  protected readonly taskMetrics?: sfn.TaskMetricsConfig;
+  protected readonly taskPolicies?: iam.PolicyStatement[];
+
+  constructor(
+    scope: Construct,
+    id: string,
+    private readonly props: HttpInvokeProps,
+  ) {
+    super(scope, id, props);
+
+    this.taskPolicies = [];
+  }
+
+  /**
+   * Provides the HTTP Invoke service integration task configuration.
+   */
+  /**
+   * @internal
+   */
+  protected _renderTask(): any {
+    return {
+      Resource: integrationResourceArn('http', 'invoke'),
+      Parameters: sfn.FieldUtils.renderObject({
+        Method: this.props.method,
+        ApiEndpoint: this.props.apiEndpoint,
+        Authentication: {
+          ConnectionArn: this.props.connectionArn,
+        },
+        RequestBody: this.props.body,
+        Headers: this.props.headers,
+        QueryParameters: this.props.queryStringParameters,
+        Transform:
+          this.props.urlEncodeBody != null
+            ? {
+              RequestBodyEncoding: 'URL_ENCODED',
+              RequestEncodingOptions: {
+                ArrayFormat:
+                  this.props.arrayEncodingFormat ??
+                  URLEncodingArrayFormat.INDICES,
+              },
+            }
+            : undefined,
+      }),
+    };
+  }
+}

packages/aws-cdk-lib/aws-stepfunctions-tasks/lib/index.ts

@@ -52,3 +52,4 @@ export * from './apigateway';
 export * from './eventbridge/put-events';
 export * from './aws-sdk/call-aws-service';
 export * from './bedrock/invoke-model';
+export * from './http/invoke';

packages/aws-cdk-lib/aws-stepfunctions-tasks/test/http/invoke.test.ts

@@ -0,0 +1,157 @@
+import { Stack } from '../../../core';
+import * as lib from '../../lib';
+
+let stack: Stack;
+const connectionArn =
+'arn:aws:events:us-test-1:123456789012:connection/connectionName';
+
+const expectTaskWithParameters = (task: lib.HttpInvoke, parameters: any) => {
+  expect(stack.resolve(task.toStateJson())).toEqual({
+    Type: 'Task',
+    Resource: {
+      'Fn::Join': [
+        '',
+        [
+          'arn:',
+          {
+            Ref: 'AWS::Partition',
+          },
+          ':states:::http:invoke',
+        ],
+      ],
+    },
+    End: true,
+    Parameters: parameters,
+  });
+};
+
+describe('AWS::StepFunctions::Tasks::HttpInvoke', () => {
+  beforeEach(() => {
+    stack = new Stack();
+  });
+
+  test('invoke with default props', () => {
+    const task = new lib.HttpInvoke(stack, 'Task', {
+      apiEndpoint: 'https://api.example.com',
+      connectionArn,
+      method: 'POST',
+    });
+
+    expectTaskWithParameters(task, {
+      ApiEndpoint: 'https://api.example.com',
+      Authentication: {
+        ConnectionArn: connectionArn,
+      },
+      Method: 'POST',
+    });
+  });
+
+  test('invoke with request body', () => {
+    const task = new lib.HttpInvoke(stack, 'Task', {
+      apiEndpoint: 'https://api.example.com',
+      body: JSON.stringify({ foo: 'bar' }),
+      connectionArn,
+      method: 'POST',
+    });
+
+    expectTaskWithParameters(task, {
+      ApiEndpoint: 'https://api.example.com',
+      Authentication: {
+        ConnectionArn: connectionArn,
+      },
+      Method: 'POST',
+      RequestBody: JSON.stringify({ foo: 'bar' }),
+    });
+  });
+
+  test('invoke with headers', () => {
+    const task = new lib.HttpInvoke(stack, 'Task', {
+      apiEndpoint: 'https://api.example.com',
+      connectionArn,
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      method: 'POST',
+    });
+
+    expectTaskWithParameters(task, {
+      ApiEndpoint: 'https://api.example.com',
+      Authentication: {
+        ConnectionArn: connectionArn,
+      },
+      Method: 'POST',
+      Headers: {
+        'Content-Type': 'application/json',
+      },
+    });
+  });
+
+  test('invoke with query string parameters', () => {
+    const task = new lib.HttpInvoke(stack, 'Task', {
+      apiEndpoint: 'https://api.example.com',
+      connectionArn,
+      method: 'POST',
+      queryStringParameters: {
+        foo: 'bar',
+      },
+    });
+
+    expectTaskWithParameters(task, {
+      ApiEndpoint: 'https://api.example.com',
+      Authentication: {
+        ConnectionArn: connectionArn,
+      },
+      Method: 'POST',
+      QueryParameters: {
+        foo: 'bar',
+      },
+    });
+  });
+
+  test('invoke with request body encoding and default arrayEncodingFormat', () => {
+    const task = new lib.HttpInvoke(stack, 'Task', {
+      apiEndpoint: 'https://api.example.com',
+      method: 'POST',
+      connectionArn,
+      urlEncodeBody: true,
+    });
+
+    expectTaskWithParameters(task, {
+      ApiEndpoint: 'https://api.example.com',
+      Authentication: {
+        ConnectionArn: connectionArn,
+      },
+      Method: 'POST',
+      Transform: {
+        RequestBodyEncoding: 'URL_ENCODED',
+        RequestEncodingOptions: {
+          ArrayFormat: lib.URLEncodingArrayFormat.INDICES,
+        },
+      },
+    });
+  });
+
+  test('invoke with request body encoding and arrayEncodingFormat', () => {
+    const task = new lib.HttpInvoke(stack, 'Task', {
+      apiEndpoint: 'https://api.example.com',
+      arrayEncodingFormat: lib.URLEncodingArrayFormat.BRACKETS,
+      connectionArn,
+      method: 'POST',
+      urlEncodeBody: true,
+    });
+
+    expectTaskWithParameters(task, {
+      ApiEndpoint: 'https://api.example.com',
+      Authentication: {
+        ConnectionArn: connectionArn,
+      },
+      Method: 'POST',
+      Transform: {
+        RequestBodyEncoding: 'URL_ENCODED',
+        RequestEncodingOptions: {
+          ArrayFormat: lib.URLEncodingArrayFormat.BRACKETS,
+        },
+      },
+    });
+  });
+});