New: [AEA-6256] - StateMachine construct

packages/cdkConstructs/src/constructs/RestApiGateway/StateMachineEndpoint.ts

@@ -0,0 +1,74 @@
+import {IResource, PassthroughBehavior, StepFunctionsIntegration} from "aws-cdk-lib/aws-apigateway"
+import {IRole} from "aws-cdk-lib/aws-iam"
+import {HttpMethod} from "aws-cdk-lib/aws-lambda"
+import {Construct} from "constructs"
+import {stateMachineRequestTemplate} from "./templates/stateMachineRequest.js"
+import {stateMachine200ResponseTemplate, stateMachineErrorResponseTemplate} from "./templates/stateMachineResponses.js"
+import {ExpressStateMachine} from "../StateMachine.js"
+
+/** Parameters used to create an API endpoint backed by a Step Functions Express workflow. */
+export interface StateMachineEndpointProps {
+  /** Parent API resource under which the state machine endpoint is added. */
+  parentResource: IResource
+  /** Path segment used to create the child API resource. */
+  readonly resourceName: string
+  /** HTTP verb bound to the Step Functions integration. */
+  readonly method: HttpMethod
+  /** Invocation role used by API Gateway when starting workflow executions. */
+  restApiGatewayRole: IRole
+  /** State machine wrapper construct providing the target workflow ARN and integration target. */
+  stateMachine: ExpressStateMachine
+}
+
+/** Adds an API Gateway resource/method that starts an Express Step Functions execution. */
+export class StateMachineEndpoint extends Construct {
+  /** API resource created by this construct. */
+  resource: IResource
+
+  /** Wires request and response mapping templates for JSON and FHIR payload flows. */
+  public constructor(scope: Construct, id: string, props: StateMachineEndpointProps) {
+    super(scope, id)
+
+    const requestTemplate = stateMachineRequestTemplate(props.stateMachine.stateMachine.stateMachineArn)
+
+    const resource = props.parentResource.addResource(props.resourceName)
+    resource.addMethod(props.method, StepFunctionsIntegration.startExecution(props.stateMachine.stateMachine, {
+      credentialsRole: props.restApiGatewayRole,
+      passthroughBehavior: PassthroughBehavior.WHEN_NO_MATCH,
+      requestTemplates: {
+        "application/json": requestTemplate,
+        "application/fhir+json": requestTemplate
+      },
+      integrationResponses: [
+        {
+          statusCode: "200",
+          responseTemplates: {
+            "application/json": stateMachine200ResponseTemplate
+          }
+        },
+        {
+          statusCode: "400",
+          selectionPattern: String.raw`^4\d{2}.*`,
+          responseTemplates: {
+            "application/json": stateMachineErrorResponseTemplate("400")
+          }
+        },
+        {
+          statusCode: "500",
+          selectionPattern: String.raw`^5\d{2}.*`,
+          responseTemplates: {
+            "application/json": stateMachineErrorResponseTemplate("500")
+          }
+        }
+      ]
+    }), {
+      methodResponses: [
+        { statusCode: "200" },
+        { statusCode: "400" },
+        { statusCode: "500" }
+      ]
+    })
+
+    this.resource = resource
+  }
+}

packages/cdkConstructs/src/constructs/RestApiGateway/templates/stateMachineRequest.ts

@@ -0,0 +1,60 @@
+/* eslint-disable max-len */
+/**
+ * @returns API Gateway request mapping template for StartExecution payloads.
+ */
+export const stateMachineRequestTemplate = (stateMachineArn: string) => {
+  return `## Velocity Template used for API Gateway request mapping template
+## "@@" is used here as a placeholder for '"' to avoid using escape characters.
+
+#set($includeHeaders = true)
+#set($includeQueryString = true)
+#set($includePath = true)
+#set($requestContext = '')
+
+#set($inputString = '')
+#set($allParams = $input.params())
+#set($allParams.header.apigw-request-id = $context.requestId)
+{
+    "stateMachineArn": "${stateMachineArn}",
+    #set($inputString = "$inputString,@@body@@: $input.body")
+    #if ($includeHeaders)
+        #set($inputString = "$inputString, @@headers@@:{")
+        #foreach($paramName in $allParams.header.keySet())
+            #set($inputString = "$inputString @@$paramName@@: @@$util.escapeJavaScript($allParams.header.get($paramName))@@")
+            #if($foreach.hasNext)
+                #set($inputString = "$inputString,")
+            #end
+        #end
+        #set($inputString = "$inputString }")
+    #end
+    #if ($includeQueryString)
+        #set($inputString = "$inputString, @@queryStringParameters@@:{")
+        #foreach($paramName in $allParams.querystring.keySet())
+            #set($inputString = "$inputString @@$paramName@@: @@$util.escapeJavaScript($allParams.querystring.get($paramName))@@")
+            #if($foreach.hasNext)
+                #set($inputString = "$inputString,")
+            #end
+        #end
+        #set($inputString = "$inputString }")
+    #end
+    #if ($includePath)
+        #set($inputString = "$inputString, @@pathParameters@@:{")
+        #foreach($paramName in $allParams.path.keySet())
+            #set($inputString = "$inputString @@$paramName@@: @@$util.escapeJavaScript($allParams.path.get($paramName))@@")
+            #if($foreach.hasNext)
+                #set($inputString = "$inputString,")
+            #end
+        #end
+        #set($inputString = "$inputString }")
+    #end
+    ## Check if the request context should be included as part of the execution input
+    #if($requestContext && !$requestContext.empty)
+        #set($inputString = "$inputString,")
+        #set($inputString = "$inputString @@requestContext@@: $requestContext")
+    #end
+    #set($inputString = "$inputString}")
+    #set($inputString = $inputString.replaceAll("@@",'"'))
+    #set($len = $inputString.length() - 1)
+    "input": "{$util.escapeJavaScript($inputString.substring(1,$len))}"
+}`
+}

packages/cdkConstructs/src/constructs/RestApiGateway/templates/stateMachineResponses.ts

@@ -0,0 +1,64 @@
+/* eslint-disable max-len */
+/** VTL response template that unwraps successful workflow output and forwards status and headers. */
+export const stateMachine200ResponseTemplate = `#set($payload = $util.parseJson($input.path('$.output')))
+#set($context.responseOverride.status = $payload.Payload.statusCode)
+#set($allHeaders = $payload.Payload.headers)
+#foreach($headerName in $allHeaders.keySet())
+    #set($context.responseOverride.header[$headerName] = $allHeaders.get($headerName))
+#end
+$payload.Payload.body`
+
+interface ErrorMap {
+  [key: string]: {
+    code: string
+    severity: string
+    diagnostics: string
+    codingCode: string
+    codingDisplay: string
+  }
+}
+
+const getOperationOutcome = (status: string) => {
+  const errorMap: ErrorMap = {
+    400: {
+      code: "value",
+      severity: "error",
+      diagnostics: "Invalid request.",
+      codingCode: "BAD_REQUEST",
+      codingDisplay: "400: The Server was unable to process the request"
+    },
+    500: {
+      code: "exception",
+      severity: "fatal",
+      diagnostics: "Unknown Error.",
+      codingCode: "SERVER_ERROR",
+      codingDisplay: "500: The Server has encountered an error processing the request."
+    }
+  }
+
+  return JSON.stringify({
+    ResourceType: "OperationOutcome",
+    issue: [
+      {
+        code: errorMap[status].code,
+        severity: errorMap[status].severity,
+        diagnostics: errorMap[status].diagnostics,
+        details: {
+          coding: [
+            {
+              system: "https://fhir.nhs.uk/CodeSystem/http-error-codes",
+              code: errorMap[status].codingCode,
+              display: errorMap[status].codingDisplay
+            }
+          ]
+        }
+      }
+    ]
+  })
+}
+
+/**
+ * @returns VTL response template that maps workflow failures to FHIR OperationOutcome payloads.
+ */
+export const stateMachineErrorResponseTemplate = (status: string) => `#set($context.responseOverride.header["Content-Type"] ="application/fhir+json")
+${getOperationOutcome(status)}`