The AWS API Gateway provides a programming model to interact with client through websockets. This article describes a sample application that provides 2 Go lambda: one to interact with the websocket and maintain its state in dynamodb; the other to send a message to all the clients using a websocket on a channel. It also provides the terraform resources to create the dynamodb table, the 2 lambdas, the gateways as well as the logs, roles, and permissions...

TL;DR: the full project is available from carnage-sh/lambda-go-websocket. It has everything you need to create a simple example.


The project content looks like below:


The main components are:

  • a dynamodb database that stores connected users with the associated channels.
  • the Rx section on the top is made of an API Gateway that handles websockets and a lambda that manages the associated logic, including the interaction with clients and how connections are handled
  • the HTTP section on the bottom is made of an API Gateway that handles interactions with a backend user who can send messages to whole channel

Terraform manifests

The AWS resources can be created with terraform and the associated manifests are available as part of the terraform directory, To apply them, it assumes you've configured and set the and files according to your needs:

  • check the aws region as part of the file
  • check to change the variables according to your needs:

    • lambda_table names the dynamodb table that will be created
    • rx and http name the API Gateway and Lambda for the RX and HTTP section of the diagram
    • rx_artifact and http_artifact name the Go artefact that should be used as functions

The Makefile as the project root can generate the artifacts with a simple make. Artifacts should be stored in terraform/bin. In addition:

  • contains data that are queried and used as part of the other manifests
  • contains the dynamodb table, index and the associated policy
  • and contain both the Lambda and API Gateway to manage the Websocket
  • and contain a Lambda an API Gateway that provide an HTTP endpoint to interact with a Websocket

To use the project, build the artifact with the make command and deploy the resource to your AWS account with the terraform apply. The manifests contain 2 outputs:

  • wscat provides the wscat syntax to interact with the RX section of the project that typically provides an echo service
  • curl provides an example with curl that allows to interact with the established websockets, i.e. run it with wscat opened in another session.

The code

The GO code allows to create 2 separate artifacts.

  • ws-linux-amd64 is built from cmd/websocket and deals with the websocket on the API Gateway. It manages connections in the dynamodb table. It also returns any message sent on the websocket to act as an echo service
  • http-linux-amd64 is built from cmd/http. It receive message from any http post, list connections from the dynamodb table and send the message to every connected websocket.

The Go code is located in the root directory, it is made of:

  • dynamodb.go that provides the code to interact with the dynamodb table
  • events.go that provides event responses for the lambda
  • handlers.go that provides the event handlers

To continue

The project provides the building blocks to use websockets in a serverless architecture with Go, AWS lambda and dynamodb. It can be used as a basis for many use cases. If you have any concerns, do not hesitate to open an issue.