The AWS API Gateway has had web socket capability since December 2018.  Web Sockets can be used for instant notifications, enabling backend services to send messages or events to one or more listeners connected to the Web Socket service.  The AWS web socket offering provides connection management and the capability for sending messages to connected listeners. The rest is up to you!  It is a great managed service primitive enabling a multitude of use cases. 

This article is intended as a Web Socket primer - it will go into the different components of the AWS API Gateway implementation and provide a primer into what you need to know when building with this service and how each component behaves, enabling you to understand the service and to build solutions effectively.  

# How Web Sockets Work

Web sockets enable a persistent, bi-directional connection between your client system and backend service.  This persistent connection creates a messaging conduit that enables data to flow in both directions, so the communication is not synchronous - it is asynchronous.  Because the message flow is bi-directional, you need to consider designing a message protocol to make sense of the data flowing from the front to the back end and vice-versa.  It is also important to note that the client when it sends a message - all it does is write the data to its outbound connection, which will send the data to the server. It won't get a response from the server - the data goes directly to the backend.

A really important distinction between API gateway HTTP requests (synchronous) and API Gateway WebSocket requests (bi-directional) is listed in the AWS documentation for Web Sockets:

> In the HTTP protocol, in which requests and responses are sent synchronously; communication is essentially one-way. In the WebSocket protocol, communication is two-way. Responses are asynchronous and are not necessarily received by the client in the same order as the client's messages were sent. In addition, the backend can send messages to the client.

You should do some design work around defining a protocol for messaging between the front and back end components - this is not as simple as building a synchronous REST API.

# Web Socket Parts

The AWS Web Socket implementation has a set of defined routes you can define and then integrate to various backend services, similar to AWS API Gateway routes.  Web Sockets provide the following standard routes: $connect, $disconnect, $default and one or more custom routes.  Each defined route has a specific function; together, they provide the building blocks for almost anything!  The $connect route also enables Authorization and/or Authentication to provide security to your web socket service. We will cover this in a deeper dive at a later time.

![Web Socket Parts](/strands/websockets/primer/sockets.png)

The diagram above shows AWS Lambda Proxies as the integration target, but the AWS API Gateway Web Socket implementation also enables other integration types (just like REST API Gateway routes):
- Lambda function (Proxy Integration)
- Lambda function (direct integration)
- HTTP Integration to integrate to an existing HTTP endpoint
- AWS Service - for a direct service integration
- VPC Link - to integrate with a service that isn't accessible over the internet.

# A Note about Routes

You do not have to define an integration for every route in the Web Socket gateway.  The AWS documentation page for $connect states that this route is optional, and it is.  The $disconnect and $default routes are also optional. However, you need at least one route to be defined with an integration for your Web Socket instance to be active and available.  The route you define could also be a **custom** route, and then your Web Socket API gateway will exist!

A common misunderstanding with Web Sockets is that you can only send data to the socket connection via the API Gateway @connections endpoint asynchronously as a notification or broadcast.  This is not the only way - the $default and custom routes that you define also have the option to return a JSON payload from the integration execution.  The response you return from your integration function is not returned like an API Gateway payload as part of a synchronous request/response cycle to the send message function of the client, so even though your integration can send back a JSON message as a response, it is still received by the client in the same way as a backend broadcast message.  This makes the backend route development similar to an API Gateway request/response and does away with requiring permission to use the @connections API.  This makes the backend configuration and implementation simpler. However, you still need to consider the design aspects of the messages that will flow between the clients and the backend of your system.

# \$connect Route

This is the first route web socket clients call to connect and create the open web socket channel for two-way communication between client and server.  As mentioned, it is also where you can add authorisation and authentication to secure your socket service, but we are not covering this detail here.  The $connect route is also optional, meaning you do not have to provide an integration if you don't need it.  In most situations, you will require a $connect integration handler when:

- You want to you want to be notified when clients connect
- You want to throttle connections or control who connects
- You want your backend to send messages back to clients using a callback URL
- You want to store the connectionId in a backend data store like DynamoDB.
- You want to enable clients to specify a subprotocol for the connection by using the Sec-Websocket-Protocol field.  You can dive deeper into Web Socket subprotocols [here](https://http.dev/ws#sec-websocket-protocol).

When you add a route for a Web Socket, the CDK enables configuration for **returnResponse** in the construct.  This configuration option is a boolean that determines if the route should send a response to the client.  This configuration option does not affect the $connect route, which will never return a response body to the web socket client.  The $connect route integration must return a **statusCode** field in the integration response payload.  The statusCode is a standard HTTP status code that indicates to the API Gateway Websocket how to respond to the client request.  A WebSocket $connect request will only be successful if a **200 HTTP Status Code** is returned, as shown in the following Lambda code snippet:

```javascript
export const onConnect = async (event) => {
	console.log('Lambda Event', JSON.stringify(event));
	// Process connection, if OK return 200  
	return {
		statusCode: 200,
	};
};
```

When the $connect route is called, the following integration event is received by your backend service.

```json
{
    "headers": {
        "Host": "p1var95tx6.execute-api.region.amazonaws.com",
        "Sec-WebSocket-Extensions": "permessage-deflate; client_max_window_bits",
        "Sec-WebSocket-Key": "a5zBM+ejSE03/ImUVVJvSQ==",
        "Sec-WebSocket-Version": "13",
        "X-Amzn-Trace-Id": "Root=1-6522959c-7af4af697cdee9f30abfbf1a",
        "X-Forwarded-For": "1.145.209.9",
        "X-Forwarded-Port": "443",
        "X-Forwarded-Proto": "https"
    },
    "multiValueHeaders": {
        "Host": [
            "p1var95tx6.execute-api.region.amazonaws.com"
        ],
        "Sec-WebSocket-Extensions": [
            "permessage-deflate; client_max_window_bits"
        ],
        "Sec-WebSocket-Key": [
            "a5zBM+ejSE03/ImUVVJvSQ=="
        ],
        "Sec-WebSocket-Version": [
            "13"
        ],
        "X-Amzn-Trace-Id": [
            "Root=1-6522959c-7af4af697cdee9f30abfbf1a"
        ],
        "X-Forwarded-For": [
            "1.145.209.9"
        ],
        "X-Forwarded-Port": [
            "443"
        ],
        "X-Forwarded-Proto": [
            "https"
        ]
    },
    "queryStringParameters": {
        "query": "hello"
    },
    "multiValueQueryStringParameters": {
        "query": [
            "hello"
        ]
    },
    "requestContext": {
        "routeKey": "$connect",
        "eventType": "CONNECT",
        "extendedRequestId": "MewPAHivSwMFWOg=",
        "requestTime": "08/Oct/2023:11:42:20 +0000",
        "messageDirection": "IN",
        "stage": "dev",
        "connectedAt": 1696765340601,
        "requestTimeEpoch": 1696765340602,
        "identity": {
            "sourceIp": "1.145.209.9"
        },
        "requestId": "MexQhHljSwMFa7A=",
        "domainName": "p1var95tx6.execute-api.region.amazonaws.com",
        "connectionId": "Mevp8c4gSwLDJJk=",
        "apiId": "p1var95tx6"
    },
    "isBase64Encoded": false
}
```

# $disconnect Route

The $disconnect route is a funny one.  It processes a disconnection from the AWS API Gateway Web Socket server.  The documentation is very explicit about how this works.  It is a best-effort event that may not reach your backend integration since the actual socket connection is already closed.  A WebSocket connection can be disconnected by either the client or the server.  The client disconnects by closing the connection, or the backend service can use the **@connections API** using the DELETE verb to close a Web Socket connection.  Use this link to dive deeper into the [@connections API](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-how-to-call-websocket-api-connections.html).
The $disconnect route does not return anything to the client (because they are no longer there).  This route should clean up any data stored by the $connect route to ensure the web socket connection is no longer registered as connected.

Your service receives the following event when the $disconnect route is called.

```json
{
    "headers":
    {
        "Host": "p1var95tx6.execute-api.region.amazonaws.com",
        "x-api-key": "",
        "X-Forwarded-For": "",
        "x-restapi": ""
    },
    "multiValueHeaders":
    {
        "Host":
        [
            "p1var95tx6.execute-api.region.amazonaws.com"
        ],
        "x-api-key":
        [
            ""
        ],
        "X-Forwarded-For":
        [
            ""
        ],
        "x-restapi":
        [
            ""
        ]
    },
    "requestContext":
    {
        "routeKey": "$disconnect",
        "disconnectStatusCode": 1000,
        "eventType": "DISCONNECT",
        "extendedRequestId": "MeyLFHBTSwMF3_Q=",
        "requestTime": "08/Oct/2023:11:48:35 +0000",
        "messageDirection": "IN",
        "disconnectReason": "",
        "stage": "dev",
        "connectedAt": 1696765340601,
        "requestTimeEpoch": 1696765715476,
        "identity":
        {
            "sourceIp": "1.145.209.9"
        },
        "requestId": "MeyLFHBTSwMF3_Q=",
        "domainName": "p1var95tx6.execute-api.region.amazonaws.com",
        "connectionId": "MexQhePZSwMCGmQ=",
        "apiId": "p1var95tx6"
    },
    "isBase64Encoded": false
}
```

# $default Route

This is the Web Socket catch-all route. When a JSON message is sent across the Web Socket connection with no handler, this route handles it.  The $default route will also handle ALL non-JSON traffic, which is sent through the Web Socket - so if you are building a service that transfers non-JSON data, this is the route you need to implement to handle your task.  If the $default route is not defined then calling an invalid route will result in a **forbidden** error as shown here:

```json
{
	"message": "Forbidden",
	"connectionId": "Mid3qegySwMCEhg=",
	"requestId": "Mifl6EhjSwMF3Kw="
}
```

# Custom Routes

Custom routes enable you to create a specific set of handlers based on the content of JSON messages sent through the web socket from connected clients.  By default, the route selector uses `$request.body.action`, but you can set this to many different options. Read through the detailed documentation on the AWS API Gateway docs [here](https://docs.aws.amazon.com/apigateway/latest/developerguide/websocket-api-develop-routes.html#apigateway-websocket-api-route-selection-expressions) to understand the nuances of how web sockets route messages to your custom Lambda code. There are a lot of flexible options.

Here is an example message for the default configuration using **\$request.body.action** to route to your Lambda function.  What is interesting about the **routeSelectionExpression** is how you can combine multiple attributes to create a concatenated key to create nested routes, e.g. `${request.body.service}/${request.body.action}` which creates a **routeKey** of **"order/test"** (shown in the JSON example below).

```json
{
    "requestContext":
    {
        "routeKey": "order/test",
        "messageId": "MewPAdCASwMCIWw=",
        "eventType": "MESSAGE",
        "extendedRequestId": "MewPAHivSwMFWOg=",
        "requestTime": "08/Oct/2023:11:35:21 +0000",
        "messageDirection": "IN",
        "stage": "dev",
        "connectedAt": 1696764684191,
        "requestTimeEpoch": 1696764921301,
        "identity":
        {
            "sourceIp": "1.255.255.255"
        },
        "requestId": "MewPAHivSwMFWOg=",
        "domainName": "p1var95tx6.execute-api.region.amazonaws.com",
        "connectionId": "Mevp8c4gSwLDJJk=",
        "apiId": "p1var95tx6"
    },
    "body": "{ \n \"service\": \"order\",\n   \"action\": \"test\",\n    \"data\": {\n        \"item\": \"value\"\n    }\n}",
    "isBase64Encoded": false
}
```

# Summary of Lambda Response Modes

- **$connect:** only cares about the **statusCode** returned by your Lambda response.  All other data is ignored.
- **$disconnect:** doesn't care about any response data - the client is already gone, so do your cleanup here!
- **$default:** Only cares about the **body** in the API gateway response, and even then, **only** when you have explicitly configured the integration to **returnResponse**.  **body** and **headers** returned in the Lambda response will be ignored.
- **custom:** Is the same as the $default route - only the actual **body** matters and **only** when you have  **"true"** in the **returnResponse** configuration option.

# API Gateway Web Socket Quotas and Limits

We can't complete the primer without listing the standard set of quotas and limits that apply to Web Sockets, which are critical for building production-ready solutions.  A summary of the main critical ones is here. For the exhaustive list, see quotas and limits in the [AWS documentation](https://docs.aws.amazon.com/apigateway/latest/developerguide/limits.html#apigateway-execution-service-websocket-limits-table).

- Message size is limited to a maximum of 128KB, anything larger will result in the web socket being disconnected with a **1009 Message too big** error.
- Connection duration limit is 2 hours.  After 2 hours, the web socket connection will be closed, and the client must reconnect.
- Idle Connection timeout - 10 minutes.  After 10 minutes of idle time, the web socket connection will be terminated, and the client must reconnect.
- API Gateway integration processing limit is 29 seconds for a Web Socket message.  When your backend integration takes longer than 29 seconds, the client will receive an error message like the following:

```json
{
	"message": "Endpoint request timed out",
	"connectionId": "MiWsnfkgywMCF9A=",
	"requestId": "MiXn3HRWSwMFUHA="
}
```

**Important Note on timeouts** - like API Gateway integrations, the API gateway will return a timeout error to the Web Socket connection. However, the backend integration may continue to process up to its limit as per normal API gateway REST request/response.

To test this further, I set up a Lambda route with a lambda timeout set to 2 minutes and made the Lambda process sleep for 45 seconds.  After 29 seconds, the web socket client received the API Gateway request timeout error, but the actual lambda continued and completed its execution, as expected.

# Summary

Web Sockets are a great bi-directional message channel enabling efficient front to back-end communications.  They use a connection-oriented protocol, so you will need a strategy in your overall design to deal with critical notifications when the client is not connected to the web socket.  This is quite an issue with apps built entirely for the mobile phone market where the networks are prone to drop-outs or moments of disconnections due to signal blockage.  Design with connection drop-outs in mind, and with the limits in mind such as web socket disconnect timeouts (after 10 minutes of inactivity) or hard connection limit timeouts (2 hours maximum connection time).

A common use case for Web sockets is one where backend services send broadcasts to all connected clients.  This use case requires the use of a back-end data store to store connection details for sending the broadcasts out.  If your solution is for receiving notifications about a back-end task you kicked off, you don't need to create a database.  You can use the $request.requestContext.connectionId to send the job status updates to the client starting the back-end task without a database.

Like all AWS Managed Service offerings, understand the quotas and limits that apply to the service and ensure your design considers these constraints as first-class citizens - this is the key to success when building with a Serverless First mindset.

Take into account the routes you need to define. You only need a single route to be defined for the WebSocket API gateway to be initialised and deployed as a working entity. See the **A Note about Routes** section for more details.  If you need to secure your web socket connections, you will need a **$connect** route defined, and you will need to add security control onto this API gateway (security will be covered in a separate post).

# More Reading

- If you want to go deeper into learning about Web Sockets, there is a more technical description available [here](https://http.dev/ws#).
- Learn more about registered WebSocket Sub Protocols [here](https://www.iana.org/assignments/websocket/websocket.xml#subprotocol-name).
- Allen Helton (AWS Serverless Hero) has also published a great series covering Web Sockets on his [Ready Set Cloud Blog](https://www.readysetcloud.io/blog/allen.helton/intro-to-aws-websockets/).


A Web Socket Primer

In the AWS Serverless world, we are often constrained by Managed Service limits.  A common limit causing friction is the API Gateway timeout, which is 29 seconds.  Any process you trigger through an API Gateway route must be completed before this time expires, or the API Gateway will return an HTTP 502 Bad Gateway error indicating a backend service timeout.  This same constraint applies to routes triggered via the API Gateway V2 Web Socket service.  What makes this timeout more confusing is that the back-end integration has already started and will continue processing until it finishes, so if the client re-launches the task, thinking it simply terminated prematurely, you will end up with multiple long-running tasks being executed for no reason!

There are a variety of strategies you can use to resolve this problem.  The solutions revolve around disconnecting the task execution and completion steps, making the client/server interactions asynchronous.  To resolve this, we can set up a database and a polling API to enable a client to submit a task using one API and then create another API for the client to poll for task completion.  This is quite wasteful of compute resources and can be seen as a simple solution, but it can be complicated to implement and get exactly right.

This is where web sockets can come in handy. We can use a web socket as a bi-directional communication channel between our client application and backend processes, and we end up with an interaction like the following high-level diagram.

![High level EDA flow - how socket tasks work](/strands/websockets/async-task-runner/socket-tasks-eda-flow.png)

With web sockets in the picture, we can set up an end-to-end event-driven loop from client to server and back to client.  This solution can be very compute efficient and does not require the client to maintain a loop and continually poll for the resolution of the long-running task.

> **Did you know you don't need a DynamoDB table to use Web Sockets?**
> Nearly every Web Socket article I have seen includes a DynamoDB or other data store.  In this use case we are covering here, there is no need for a DynamoDB.  You only need a data store when you want to Broadcast notifications from your backend service to collections of connected web sockets (we will cover this use case in another article).

## How does it all work?

1. The Client sends a **Start Task** message to the Web Socket
2. The Web Socket API sends a **Start Task** message to the Long Running Task, and when this has been done, it immediately acknowledges the message from the client.
3. The Client does not wait for the Long Running Task to complete - it waits long enough for the Web Socket infrastructure to acknowledge the message as successful. It can happily do something else, knowing it will be notified when the task is done.
4. The running of the Long Running Task is a "Set and Forget" action for the client and the Web Socket API.
5. The Long Running task will execute, and when it is finished, it will send a notification back to the Client who started it.

## The Detailed Solution Design

The following diagram shows a detailed flow diagram of the service interactions for executing a long-running task and being notified of its outcome via an API Gateway web socket interface.  I have colour-coded the arrows for the services' Asynchronous (blue) and Synchronous (green) interactions.  Notice there is no data store required for this use case (DynamoDB is not required).

![Socket Tasks EDA Architecture](/strands/websockets/async-task-runner/socket-tasks-arch.png)

The solution revolves around AWS EventBridge as the event routing mechanism to ensure the web socket API request executes the correct task.  I like EventBridge for this purpose, but you could also use SNS or SQS to launch asynchronous tasks or execute a Lambda directly using the async invoke SDK.  The key driver in the architecture is the dotted **BYO Long Running Task**, where you can plug in your long-running lambda task to be executed.  Each long-running task will be executed and the result from the task will be forwarded using Lambda destinations to the **task-notify queue** which will enable the task result to be sent back to the initiating WebSocket connection.  The design above shows a single Lambda function, but since we use EventBridge as the driver, you can configure as many long-running tasks as you need.

## Building the Solution

I have created a CDK construct called **SocketTasks** that creates the entire solution shown in the architecture diagram.  The construct accepts a list of tasks, each with one or more task types.  The **type** is defined as an array, allowing multiple lambda tasks to be created and managed.  Each task "type" definition creates an **EventBridgeRule** to trigger the task (or tasks).  

```typescript
new SocketTasks(this, `tasks`, 
  {
    taskFunctions: [
      {
        type: ["task-type"],
        func: handlerOne,
      },
      {
        type: ["task-type-2"],
        func: handlerTwo,
      },
    ],
  }
);
```

Using the above properties, you can submit an array of tasks to be executed using the task properties:

- **type:** defines EventBridge rules matching one or more values in the **detail-type** event attribute.  Adding multiple strings into the **type** array will configure a multi-match rule in EventBridge, giving your task more than a single trigger.
- **func:** refers to an instance of the AWS CDK Lambda function construct.

The lambda function you provide must accept an EventBridge event, which contains the task data using the EventBridge message fields, which are shown below:

```typescript
{
  version: '0',
  id: 'ab0b3376-4917-bbd7-aa1f-7274525ca86e',
  'detail-type': 'task-type',
  source: 'task-id:::connection-id',
  account: '3099999999996149415',
  time: '2023-10-15T02:42:33Z',
  region: 'ap-southeast-2',
  resources: [],
  detail: { key1: 'value', id: 'my-id' }
}
```

- **detail-type**: Defines the type of task triggered by the web socket message.
- **source**: This field contains both the submitted **task-id** from the original message and the **connection-id** of the web socket connection submitting the task. These two fields are used in sending the response to the originating caller.  The task-id value is required to provide the context of the task response being sent via the web socket response so the caller can match the response to the original request.
- **detail**: The detail field contains the input payload for the submitted task.

## Socket Task Construct Components

The **SocketTask** construct creates all the services shown in the architecture diagram above. It will add the Lambda destination configuration to each task's provided Lambda function to send success or failure messages to the SQS queue.  You will notice there is no database required in this particular design.  The connectionId of the WebSocket submitting the task is passed through the components, enabling the task-notify handler to send the response to the correct web socket.

### Web-Socket Gateway

This is the web socket entry point where the route is defined, which passes the client task data to the **task-submit** lambda.  

### Task-Submit Lambda

This Lambda packages the task data into a message sent to the **Task Bus**, triggering the actual Lambda function (or functions) to run your task(s).

### Task Bus

This is an EventBridge event bus with rules defined to trigger one or more long-running tasks.  The construct enables passing in your own EventBus instance so you can incorporate the design into an existing solution.

### BYO Long Running Task (or Tasks)

This specific long-running task will be started by an event bus message being sent to it.  This Lambda will be invoked Asynchronously by the EventBridge service, and the success or failure of the task will be forwarded via Lambda Destinations to the **task-notify Queue**.  There is no restriction on the lambda function you specify other than it can be invoked by an EventBridge message, and it does not have a Lambda destinations configuration.

The lambda function should return the response you expect to be returned to the initiator.  The function provided to the L3 construct does not need to have Lamdba destinations configured - the construct does this for you (construct magic).  You also do not need to worry about the connectionId detail to return the task response to the task initiator - this is all handled transparently by the construct components.

The benefit of using Lambda Destinations for the Asynchronous Lambda invocation by Event Bridge is that the actual context of the Lambda failure is included in the message payload submitted to the SQS queue.  Following is an example of a failed task and the message submitted into the SQS queue for the notification.

The key section is the **requestContex**t, which contains information about what happened. The **requestPayload**, with the input message and the **requestResponse**, contains the actual response from the Lambda function.  This is all great information for troubleshooting (in case of errors).

In the following example, you will notice the Task resulted in an **unhandled** error, and the requestContext shows its condition as **RetriesExhausted**, indicating that the task failed multiple times and further retries were not possible (this is something I love about LambdaDestinations).

```typescript
{
  version: '1.0',
  timestamp: '2023-10-15T01:50:01.584Z',
  requestContext: {
    requestId: '20243f12-99ff-4469-b04d-895ef0ffee9d',
    functionArn: 'arn:aws:lambda:ap-southeast-2:308836149415:function:socket-tasks-example-handlertwoAB0797C6-83siD3o6sadS:$LATEST',
    condition: 'RetriesExhausted',
    approximateInvokeCount: 3
  },
  requestPayload: {
    version: '0',
    id: '0b6d4601-4a6c-6b97-0453-1c6d942c3843',
    'detail-type': 'task-type-2',
    source: 'M0en2eVpSwMCFmw=',
    account: '308836149415',
    time: '2023-10-15T01:47:10Z',
    region: 'ap-southeast-2',
    resources: [],
    detail: { key1: 'value' }
  },
  responseContext: {
    statusCode: 200,
    executedVersion: '$LATEST',
    functionError: 'Unhandled'
  },
  responsePayload: {
    errorType: 'Error',
    errorMessage: 'Task Processing failed',
    trace: [
      'Error: Task Processing failed',
      '    at Runtime.taskFailFunc [as handler] (/var/task/index.js:33:9)',
      '    at Runtime.handleOnceNonStreaming (file:///var/runtime/index.mjs:1147:29)'
    ]
  }
}

```

### Task-Notify Queue

Receives the success or fail message from the long-running task and will trigger the **task-notify** lambda.  The queue is the destination for both successful and failed tasks. The notifier will send the result to the initiator via the web socket channel.  The construct enables you to pass in your own SQS instance in case you have existing security policies or constraints that need to be incorporated.

### Task-Notify Lambda

This lambda is responsible for taking the messages from the SQS trigger and processing the Lambda Destination message to craft a response to the client requesting the task via the **web-socket Gateway**.  The message will be sent to the listening client via the web socket connection.

### Key Design Decisions

Several key decisions are needed to make the process described in the previous section work.  One of the main key decisions is deciding on the message format between the client and backend services.  In the Web Socket Primer article, I provided links to common Web Socket Sub-Protocols that are published.  These Sub-Protocols are a description of Message Formats and what they mean.  For your web socket implementation to be successful, create a message design so everyone knows how to talk and what they are doing!

Here is the request message the client sends to the web socket to start a long-running task.

```json
{
    "action": "task-submit",
    "task": {
        "id": "my-id",
        "type": "task-type",
        "data": {
            "key1": "value"
        }
    }
}
```

**action:** routes the message to the **task-submit** lambda function for processing, this is essential for Websocket API routing to the specific handler.
**task**: Object defining the task.
 **id:** Client-assigned identifier for the task being requested.  This is so the client can keep track of requests and match up the responses when they return.  Web socket communications are asynchronous and tasks will take different times to run so the responses will not come back in any particular order.
 **type:** This is the key to identifying the long-running task to start.
 **data:** This is a custom data object defining input data for the long-running task to use.

Here is the response message sent from the server to the client.

```json
{
 "task_id": "my-id",
 "status": "Success",
 "response": {
  "statusCode": 200,
  "body": "{\"output\":\"completed task data\"}"
 }
}
```

**task_id:** The value the client sends in the request `task.id`.
**status:** Either **Success** or **Fail**, indicating if the task succeeded.
response: Data sent as a part of the Lambda destination handling from the long-running task lambda.
 **statusCode:** Contains an HTTP statusCode for tasks.
 **body:** Contains a JSON object in an escaped string form.  The string can be turned into a JSON object using JSON parsing functions in many popular programming languages.  The **body** is the actual Lambda response received in the lambda destinations message.

## Summary

In this article, I introduced a use case for WebSockets that does not use a DynamoDB table for sending notifications.   I also introduced a method for executing long-running tasks asynchronously using AWS Lambda and provided a custom CDK construct to leverage this solution in your cloud.  This solution requires a connected WebSocket environment for executing tasks, so your client needs to be able to keep the connection open for the time it takes to execute.

Another key design process you must consider with WebSockets is the actual communication protocol between client and server components.  This needs to be defined, or you may end up with a big ball of mud.

Check out [Serverless DNA Constructs on GitHub](https://github.com/serverless-dna/constructs), I will add more constructs over time for different use cases to help accelerate your projects.  I welcome feedback, so do create issues and discussions to help drive what gets developed next!

If you want to know how to leverage the [Serverless DNA Constructs](https://github.com/serverless-dna/constructs) take a look at our published collection of [Constructs Examples](https://github.com/serverless-dna/constructs-examples) to fast-track your development.


Tame Long Running Tasks with Web Sockets!

Two-way instant communication is powerful and API gateway has a Web Socket managed service to get you going quickly and easily.
