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


Web Sockets have become a fundamental technology in modern web development, but their true function is often misunderstood. The killer use-case for Web Sockets has been in the development and proliferation of chat apps where users jump into a channel and write messages to one another.  This has led to a wide spread understanding that Web Sockets provide publish and subscribe capability for your application - but this is a myth - Web Sockets do not Pub-Sub.  In this article you will learn  about Web Sockets, what they do and how they fit into your application architecture and common uses for Web Sockets in web application development.

## What are Web Sockets?

Web Sockets represent a communication protocol that creates a persistent connection between a client (typically a web browser) and a server. Unlike traditional HTTP, which follows a request-response pattern, Web Sockets allow:

- **Two-way communication**: Both server and client can send messages at any time
- **Persistent connection**: One connection stays open instead of creating new ones for each interaction.
- **Low latency**: Messages transmit immediately without the overhead of establishing new connections

Before Web Sockets, developers used techniques like HTTP polling, where browsers would repeatedly ask servers "Do you have anything new for me?". This is inefficient and causes delays. Web Sockets solved this problem by creating a direct communication channel that stays open enabling servers to send data directly to clients as soon as it is available which enables powerful real-time bi-directional communication.

## How Web Sockets Work?

WebSocket connections are an instance of an upgraded standard HTTP connection over TCP.  When connecting to a web server with the “wss” protocol - the server attempts to upgrade the connection from a standard HTTP web connection to a persistent websocket one.

This process happens in two main phases:

### The Handshake

When a client wants to establish a WebSocket connection:

1. **Initial Request**: The client sends an HTTP request that says "I'd like to upgrade this connection to Web Sockets" and ”I support these sub-protocols”.
2. **Server Verification**: The server responds with a special code confirming it accepts the WebSocket connection and also confirms the sub-protocol it prefers the client to use.
3. **Connection Established**: Once the handshake completes successfully, the HTTP connection "upgrades" to a WebSocket connection.

This handshake is designed to be compatible with HTTP infrastructure, so Web Sockets can work on standard web ports (80 and 443).

### Data Transfer

After the connection is established:

- Data is sent in units called "frames".
- Messages can be text (UTF-8) or binary data.
- Either side can send messages at any time and messages must conform to the agreed sub-protocol.
- For security, all client-to-server messages are encrypted over the TSL channel created when connecting.
- The connection stays open until either side decides to close it.

It is important to understand that with a Web Socket connection both the client and server are able to send messages to the other at anytime.  Any data written to the Web Socket will be transported to the other party.  This is where sub-protocols become important and are a critical component of the design process for an application leveraging this technology.  The way clients and servers communicate over Web Sockets is defined by the sub-protocol.

## What are SubProtocols?

Subprotocols are agreed-upon conventions for how messages should be formatted and interpreted. Think of them as languages that both client and server agree to speak.  Sub-protocols are important for:

- **Standardization**: Provide consistent ways to format messages (like JSON, XML, or custom formats)
- **Messaging Syntax**: provides the order and meaning of messages and defines any request/response style interactions and how these are tracked.  If you are using web-sockets to transfer request/response interactions these need to be carefully thought out and designed so the client and server can correlate related messages.
- **Versioning**: Allows protocols to evolve while maintaining backward compatibility
- **Interoperability**: Different implementations can work together if they follow the same subprotocol

During the handshake, the client can say "I can speak these sub-protocols" and the server responds with "Let's use this one." For example:

- A chat application might use a chat-specific sub-protocol.
- A financial application might use a different sub-protocol optimized for market data.
- A game might use yet another sub-protocol designed for real-time player movements.

By eliminating the constant request-response cycle and providing a direct communication channel, Web Sockets make interactive web applications more responsive and efficient, especially when real-time updates are essential.

## Where is the Pub-Sub?

The Web Sockets layer itself doesn’t provide any capability or functionality other than handling the client connections and transferring data between the client and server applications that sit at either end of the data pipe connection (Web Socket).

The connections starts as a normal HTTP connection with DNS Lookup and TLS handshake for a secure connection.  Once the HTTP connection is complete the client will send a standard HTTP get asking to upgrade the connection to a websocket.  It is at this point the client will include a list of sub-protocols it understands.  The server provides the client sub-protocols and asks the backend server to authorize the connection.  The backend server will respond with the sub-protocol is prefers to use from those provided by the client and whether the connection is authorized to continue.

![Web Socket Sequence diagram showing client web socket server and backend application as actors](/strands/websockets/do-not-pub-sub/ws-connect.png)

It is at this point that the connection is now established and either the client or server are able to send data to each other using the selected sub-protocol.  The client is able to send a message conforming to the sub-protocol syntax to the server for processing.  Periodically the Web Socket server may send keep-alive messages which are documented as part of the Web Socket protocol - these "Ping"-"Pong" messages are a way to ensure the connection is healthy. 

![Web Socket Sequence diagram showing client web socket server and backend application as actors](/strands/websockets/do-not-pub-sub/ws-client-message.png)

Web Sockets, being bi-directional, enables the server to also send notifications to the client.  These can occur at anytime and the client decides how to handle these.  The sub-protocol determines the structure of data to be sent between the client and server and it also dictates how each actor will respond to messages being sent.


![Web Socket Sequence diagram showing client web socket server and backend application as actors](/strands/websockets/do-not-pub-sub/ws-server-message.png)


When the client and server communications are complete, either may request to close down the connection and disconnect.

Web Sockets do not provide any functionality other than transporting data between client and server applications, it is the backend server implementation which provides the Publish and Subscribe capability.  For this reason it is essential to think about the sub-protocol your applications will use when communicating over web-sockets, without this you will have applications sending garbage to one another and not achieving anything useful.


## Considerations for Architects and Developers

Web Sockets provide the core communications capability for realtime data transfer, they handle the establishment of the connection and transfer of data.  From a client-server application perspective there are a number of challenges that Architects and Developers need to be aware of when designing and building solutions around Web Sockets.

### Connection Management

Unlike stateless HTTP, WebSocket connections create long-lived connections that must be actively managed.  Networks are often unreliable with interruptions causing connections to drop.  When you build with Web Sockets both the client and server developers must be mindful of the connections and their state - the management required is dependent on the actual features and function of the application sub-protocol being implemented.  You will need to consider the following for managing connections:

* Implementing reconnection logic with exponential backoff on both client and server
* Design for graceful handling of unexpected disconnections.
* Consider connection monitoring with Ping/Pong frames to detect "zombie" connections.
* Ensure both client and server can detect "half-open" connections where TCP remains connected but the application level communication has failed.
* Handle abrupt disconnect from clients which can occur through application crashes or browser tab closure or refresh scenarios to ensure you have clean disconnection logic.

### Message Ordering and Delivery Guarantees

Web Sockets guarantee in-order delivery on a single connection but lack mechanisms for handling reconnection scenarios.  When clients are reconnecting you need to consider the following:

* Implement application-level sequence numbers for all messages to detect missed updates.
* Build acknowledgment protocols for critical messages with timeout-based retransmission.
* Design idempotency into message handling to safely process potential duplicates during reconnection.
* Consider queuing unacknowledged messages for retransmission after re-establishing the Web Socket connection.

### State Synchronization after Disruption

Web Sockets do not provide delivery guarantees or a way to rebuild state following a disconnection.  When connections drop, there is no built-in way to determine what state was lost.  You will need to consider designing mechanism to deal with these scenarios:

* Design efficient delta synchronization protocols to minimize data transfer after reconnection.
* Consider event sourcing approaches where clients can request specific missed events.
* Build "catchup" mechanisms that determine precisely what updates a reconnecting client needs.

### Resource Management and Throttling

Web Sockets lack built-in flow control beyond TCP's mechanisms.  This places the burden of resource management and throttling on you as a service provider.  You need to consider the following:

* Implement application-level back pressure signals when receivers can't keep up with message volume
* Design rate-limiting systems that account for both message frequency and payload size
* Consider prioritization schemes for different message types during high-load scenarios
* Monitor per-connection memory usage, especially when handling large message fragments
* Implement circuit-breakers that degrade service gracefully under extreme load

### Frame Size and Message Fragmentation

Large messages create special challenges with Web Sockets.  Web Sockets typically handle a smaller message frame size (e.g. 32kb), which means larger messages are broken up into smaller chunks which need to be reconstituted on the receiving end.  You will need to:

* Design protocols that properly handle multi-frame messages, especially during connection instability
* Implement timeout mechanisms for partially received fragmented messages.
* Consider streaming approaches for large data transfers instead of single large messages.
* Test fragmentation edge cases including control frames interleaved with fragmented messages.

### Standardized Keep-Alive and Health Monitoring

Since Web Sockets are a bi-directional communication channel, both client and server are responsible for detecting the connection stability and health.  Your client and server applications will need to consider some or all of the following:

* Establish consistent Ping/Pong usage patterns across your system with clear timing parameters.
* Implement application-level heartbeats separate from WebSocket protocol mechanisms.
* Design escalating health check procedures that can distinguish between different failure modes.
* Consider how firewalls and proxies may affect long-lived connections with timeout policies.

### Request-Response Correlation

Web Sockets provide a message stream with no built-in request-response syntax.  These are left to the underlying sub-protocol to design for and consider.  In order to ensure your protocol and messaging design is robust you should consider:

* Implement message correlation IDs to match responses with their originating requests.
* Design timeout and retry mechanisms for requests that don't receive timely responses.
* Consider how concurrent operations will be managed without native request multiplexing.

### Security Implications

Long-lived connections introduce unique security concerns which must be considered in your design.  Think about some or all of the following:

* Implement periodic re-authentication without disrupting connections - tokens expire and you need to refresh them while keeping the connection alive.
* Consider rate limiting to prevent DoS attacks - both connection attempts and message frequency need monitoring.
* Define clear message validation rules in your sub-protocol - validate all incoming messages before processing them.
* Use secure WebSocket connections (wss://) in production to protect data in transit.
* Verify the Origin header to prevent cross-site WebSocket hijacking attempts.
* Implement timeouts for inactive connections to free server resources.

### Testing Strategy

Web Sockets require more complex testing approaches due to the challenges already discussed.  Think about and consider the following testing strategies to validate your solution:

- Simulate connection failures and recoveries to ensure your designs function as expected, particularly consider the failure scenarios which is where problems and edge cases will occur.
- Test partial message delivery and fragmentation to ensure your application is resilient to network interruptions.  Web Socket data occurs in frames which are smaller in size to the overall message - this adds to the testing complexities.
- Verify correct behavior under high message volumes to ensure your sub-protocol design functions correctly.

### Protocol Design

The sub-protocol you design will impact on the functioning and reliability of your application.  When thinking about the sub-protocol design you need to consider:

- Message acknowledgment mechanisms for critical updates.  If you need to guarantee a message delivery - this needs to be a specific design choice in your architecture.
- Define clear message structures with versioning support so that you can support backwards compatibility.
- Consider binary formats (Protocol Buffers, MessagePack) for high-throughput applications.

Designing messaging protocols is not easy, and must be a carefully considered part of your solution design. The sub-protocol should consider many of the elements we have discussed throughout this section, some of them are protocol specific which define the semantics of how the client and server communicate. 

## Remember Web Sockets don't Pub-Sub!

Web Sockets provide the communication channel, the responsibility for building reliable, scalable systems on top of this communication channel requires significant additional design and development effort.  In my opinion success or failure of your application design comes down to the underlying sub-protocol.  When implementing Web Sockets as your underlying communication mechanism make sure that you fully consider the impact of HOW your systems will talk - this will determine whether you succeed or fail because Web Sockets don't do pub-sub, your client and server applications do that - Web Sockets is your data pipe between them and everything else you have to build or buy!

Web Sockets Don't Pub-Sub

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.
