Add SQS-Expressjs example (#347)

* Add SQS-Expressjs example * Update Dockerfile
awslabs · Jan 21, 2024 · 1e8dee7 · 1e8dee7
1 parent 82e5ade
commit 1e8dee7
Show file tree

Hide file tree

Showing 9 changed files with 1,263 additions and 13 deletions.
diff --git a/README.md b/README.md
@@ -89,18 +89,18 @@ After passing readiness check, Lambda Web Adapter will start Lambda Runtime and
 
 The readiness check port/path and traffic port can be configured using environment variables. These environment variables can be defined either within docker file or as Lambda function configuration.
 
-| Environment Variable                                         | Description                                                                         | Default    |
-|--------------------------------------------------------------|-------------------------------------------------------------------------------------|------------|
-| AWS_LWA_PORT / PORT*                                         | traffic port                                                                        | "8080"     |
-| AWS_LWA_READINESS_CHECK_PORT / READINESS_CHECK_PORT*         | readiness check port, default to the traffic port                                   | PORT       |
-| AWS_LWA_READINESS_CHECK_PATH / READINESS_CHECK_PATH*         | readiness check path                                                                | "/"        |
-| AWS_LWA_READINESS_CHECK_PROTOCOL / READINESS_CHECK_PROTOCOL* | readiness check protocol: "http" or "tcp", default is "http"                        | "http"     |
-| AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS                 | The minimum HTTP status code that is considered unhealthy                           | "500"      |
-| AWS_LWA_ASYNC_INIT / ASYNC_INIT*                             | enable asynchronous initialization for long initialization functions                | "false"    |
-| AWS_LWA_REMOVE_BASE_PATH / REMOVE_BASE_PATH*                 | the base path to be removed from request path                                       | None       |
-| AWS_LWA_ENABLE_COMPRESSION                                   | enable gzip compression for response body                                           | "false"    |
-| AWS_LWA_INVOKE_MODE                                          | Lambda function invoke mode: "buffered" or "response_stream", default is "buffered" | "buffered" |
-| AWS_LWA_PASS_THROUGH_PATH                                    | Path to receive events payloads passed through from non-http event triggers         | "/events"  |
+| Environment Variable                                         | Description                                                                          | Default    |
+|--------------------------------------------------------------|--------------------------------------------------------------------------------------|------------|
+| AWS_LWA_PORT / PORT*                                         | traffic port                                                                         | "8080"     |
+| AWS_LWA_READINESS_CHECK_PORT / READINESS_CHECK_PORT*         | readiness check port, default to the traffic port                                    | PORT       |
+| AWS_LWA_READINESS_CHECK_PATH / READINESS_CHECK_PATH*         | readiness check path                                                                 | "/"        |
+| AWS_LWA_READINESS_CHECK_PROTOCOL / READINESS_CHECK_PROTOCOL* | readiness check protocol: "http" or "tcp", default is "http"                         | "http"     |
+| AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS                 | The minimum HTTP status code that is considered unhealthy                            | "500"      |
+| AWS_LWA_ASYNC_INIT / ASYNC_INIT*                             | enable asynchronous initialization for long initialization functions                 | "false"    |
+| AWS_LWA_REMOVE_BASE_PATH / REMOVE_BASE_PATH*                 | the base path to be removed from request path                                        | None       |
+| AWS_LWA_ENABLE_COMPRESSION                                   | enable gzip compression for response body                                            | "false"    |
+| AWS_LWA_INVOKE_MODE                                          | Lambda function invoke mode: "buffered" or "response_stream", default is "buffered"  | "buffered" |
+| AWS_LWA_PASS_THROUGH_PATH                                    | the path for receiving event payloads that are passed through from non-http triggers | "/events"  |
 
 > **Note:**
 > We use "AWS_LWA_" prefix to namespacing all environment variables used by Lambda Web Adapter. The original ones will be supported until we reach version 1.0.
@@ -161,7 +161,7 @@ Please note that `sam local` starts a Lambda Runtime Interface Emulator on port
 
 ## Non-HTTP Event Triggers
 
-Lambda Web Adapter supports non-http event triggers (such as SQS, EventBridge, and Bedrock Agents, etc.). The adapter will forward the event payload to the web application at the path specified by environment variable `AWS_LWA_PASS_THROUGH_PATH`. The default path is `/events`. The web application can retrieve the event payload from the request body. The http response body must be a valid JSON string and will be passed back as the response payload to the Lambda service.
+The Lambda Web Adapter also supports all non-HTTP event triggers, such as SQS, SNS, S3, DynamoDB, Kinesis, Kafka, EventBridge, and Bedrock Agents. The adapter forwards the event payload to the web application via a path defined by the `AWS_LWA_PASS_THROUGH_PATH` environment variable. By default, this path is set to `/events`. Upon receiving the event payload from the request body, the web application should processes it and returns the results as a JSON response. Please checkout [SQS Express.js](examples/sqs-expressjs) on how to use it.
 
 ## Examples
 
@@ -191,6 +191,7 @@ Lambda Web Adapter supports non-http event triggers (such as SQS, EventBridge, a
 - [ASP.NET MVC](examples/aspnet-mvc)
 - [ASP.NET MVC in Zip](examples/aspnet-mvc-zip)
 - [ASP.NET Web API in Zip](examples/aspnet-webapi-zip)
+- [SQS Express.js](examples/sqs-expressjs)
 
 ## Acknowledgement
 

diff --git a/examples/sqs-expressjs/.gitignore b/examples/sqs-expressjs/.gitignore
@@ -0,0 +1,14 @@
+HELP.md
+target/
+
+### IntelliJ IDEA ###
+.idea
+*.iws
+*.iml
+*.ipr
+
+### VS Code ###
+.vscode/
+
+.aws-sam
+node_modules
diff --git a/examples/sqs-expressjs/README.md b/examples/sqs-expressjs/README.md
@@ -0,0 +1,106 @@
+# SQS Express.js example
+
+This project demonstrates the integration of Amazon Simple Queue Service (SQS) with an Express.js application. It showcases how to effectively manage and process messages from an SQS queue within an Express.js application environment.
+
+In this Express.js application integrated with Amazon SQS, there is no explicit code required to poll the SQS queue. The AWS Lambda handles the polling of the SQS queue and Lambda Web Adapter forwards the event payload to the Express.js application. This simplifies the application code and allows developers to focus on processing the event payload rather than managing the queue polling logic.
+
+The application can be deployed in an AWS account using the [Serverless Application Model](https://github.com/awslabs/serverless-application-model). The `template.yaml` file in the root folder contains the application definition.
+
+The top level folder is a typical AWS SAM project. The `app` directory is an express.js application with a [Dockerfile](app/Dockerfile).
+
+```dockerfile
+FROM public.ecr.aws/docker/library/node:20-slim
+COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.8.0 /lambda-adapter /opt/extensions/lambda-adapter
+ENV PORT=8000 AWS_LWA_READINESS_CHECK_PROTOCOL=tcp
+WORKDIR "/var/task"
+ADD src/package.json /var/task/package.json
+ADD src/package-lock.json /var/task/package-lock.json
+RUN npm install --omit=dev
+ADD src/ /var/task
+CMD ["node", "index.js"]
+```
+
+Line 2 copies lambda adapter binary into /opt/extenions. This is the only change to run the express.js application on Lambda.
+
+```dockerfile
+COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.8.0 /lambda-adapter /opt/extensions/lambda-adapter
+```
+
+## Pre-requisites
+
+The following tools should be installed and configured.
+
+* [AWS CLI](https://aws.amazon.com/cli/)
+* [SAM CLI](https://github.com/awslabs/aws-sam-cli)
+* [Node](https://nodejs.org/en/)
+* [Docker](https://www.docker.com/products/docker-desktop)
+
+## Build
+
+Navigate to the sample's folder and use the SAM CLI to build a container image
+
+```shell
+sam build
+```
+## Deploy
+
+This command compiles the application and prepares a deployment package in the `.aws-sam` sub-directory.
+
+To deploy the application in your AWS account, you can use the SAM CLI's guided deployment process and follow the instructions on the screen
+
+```shell
+sam deploy --guided
+```
+
+Please take note of the container image name.
+Once the deployment is completed, the SAM CLI will print out the stack's outputs, including the new sqs queue URL.
+
+```shell
+...
+---------------------------------------------------------------------------------------------------------------------------------------
+Outputs                                                                                                                               
+---------------------------------------------------------------------------------------------------------------------------------------
+Key                 SqsQueueUrl                                                                                                       
+Description         SQS URL the express Lambda Function will receive messages from                                                    
+Value               https://sqs.us-west-2.amazonaws.com/xxxxxxxx/xxxxxxxx                                                    
+---------------------------------------------------------------------------------------------------------------------------------------
+
+```
+
+## Test
+
+Use the following command to send a message to the sqs queue.
+
+```shell
+aws sqs send-message --queue-url <replace with your sqs queue url> --message-body "Hello from CLI"
+```
+
+Run the following command to see the Lambda function's CloudWatch logs.
+
+```shell
+sam logs --tail --stack-name <replace with your stack name>
+```
+
+## Local Test
+
+You can also use SAM CLI for local testing.
+
+```shell
+sam local invoke SqsExpressFunction -e events/sqs.json
+```
+
+Here is a sample output from this command.
+
+```shell
+Invoking Container created from sqsexpressfunction:v1                                                                            
+Building image.................
+Using local image: sqsexpressfunction:rapid-x86_64.                                                                              
+
+START RequestId: ceaaf9bb-8d8c-42a5-828c-a5d4c8a506f1 Version: $LATEST
+Example app listening at http://localhost:8000
+Received event: {"Records":[{"messageId":"19dd0b57-b21e-4ac1-bd88-01bbb068cb78","receiptHandle":"MessageReceiptHandle","body":"Hello from SQS!","attributes":{"ApproximateReceiveCount":"1","SentTimestamp":"1523232000000","SenderId":"123456789012","ApproximateFirstReceiveTimestamp":"1523232000001"},"messageAttributes":{},"md5OfBody":"7b270e59b47ff90a553787216d55d91d","eventSource":"aws:sqs","eventSourceARN":"arn:aws:sqs:us-east-1:123456789012:MyQueue","awsRegion":"us-east-1"}]}
+processing message: 19dd0b57-b21e-4ac1-bd88-01bbb068cb78 with body: Hello from SQS!
+END RequestId: ceaaf9bb-8d8c-42a5-828c-a5d4c8a506f1
+REPORT RequestId: ceaaf9bb-8d8c-42a5-828c-a5d4c8a506f1  Init Duration: 0.10 ms  Duration: 117.12 ms     Billed Duration: 118 ms Memory Size: 1024 MB     Max Memory Used: 1024 MB
+"success"
+```
diff --git a/examples/sqs-expressjs/app/Dockerfile b/examples/sqs-expressjs/app/Dockerfile
@@ -0,0 +1,9 @@
+FROM public.ecr.aws/docker/library/node:20-slim
+COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.8.0 /lambda-adapter /opt/extensions/lambda-adapter
+ENV PORT=8000 AWS_LWA_READINESS_CHECK_PROTOCOL=tcp
+WORKDIR "/var/task"
+ADD src/package.json /var/task/package.json
+ADD src/package-lock.json /var/task/package-lock.json
+RUN npm install --omit=dev
+ADD src/ /var/task
+CMD ["node", "index.js"]
diff --git a/examples/sqs-expressjs/app/src/index.js b/examples/sqs-expressjs/app/src/index.js
@@ -0,0 +1,26 @@
+const express = require('express')
+const bodyParser = require('body-parser')
+
+const app = express()
+const port = process.env['PORT'] || 8080
+
+// setup bodyParser to parse application/json
+app.use(bodyParser.json())
+
+
+// LWA sends SQS messages to this endpoint, use environment variable 'AWS_LWA_PASS_THROUGH_PATH' to configure this path
+app.post('/events', (req, res) => {
+    console.log(`Received event: ${JSON.stringify(req.body)}`)
+
+    // printout the message Id and body
+    req.body.Records.forEach((record) => {
+        console.log(`processing message: ${record.messageId} with body: ${record.body}`)
+    })
+
+    // send a 200 response with json string 'success'
+    res.json('success')
+})
+
+app.listen(port, () => {
+    console.log(`Example app listening at http://localhost:${port}`)
+})