Skip to content

Commit 6fb66d0

Browse files
joe4devjoe4dev
committed
Add JavaScript sample
1 parent 80703e2 commit 6fb66d0

File tree

12 files changed

+508
-0
lines changed

12 files changed

+508
-0
lines changed

‎lambda-debugging-sam-javascript/.gitignore‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# Lambda function response
2+
response.json
3+
4+
# Lambda function package
5+
hello-world/hello-world-javascript.zip
6+
7+
# Created by https://www.toptal.com/developers/gitignore/api/node,sam
8+
# Edit at https://www.toptal.com/developers/gitignore?templates=node,sam
9+
10+
### Node ###
11+
# Logs
12+
logs
13+
*.log
14+
npm-debug.log*
15+
yarn-debug.log*
16+
yarn-error.log*
17+
lerna-debug.log*
18+
.pnpm-debug.log*
19+
20+
# Diagnostic reports (https://nodejs.org/api/report.html)
21+
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
22+
23+
# Runtime data
24+
pids
25+
*.pid
26+
*.seed
27+
*.pid.lock
28+
29+
# Directory for instrumented libs generated by jscoverage/JSCover
30+
lib-cov
31+
32+
# Coverage directory used by tools like istanbul
33+
coverage
34+
*.lcov
35+
36+
# nyc test coverage
37+
.nyc_output
38+
39+
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
40+
.grunt
41+
42+
# Bower dependency directory (https://bower.io/)
43+
bower_components
44+
45+
# node-waf configuration
46+
.lock-wscript
47+
48+
# Compiled binary addons (https://nodejs.org/api/addons.html)
49+
build/Release
50+
51+
# Dependency directories
52+
node_modules/
53+
jspm_packages/
54+
55+
# Snowpack dependency directory (https://snowpack.dev/)
56+
web_modules/
57+
58+
# TypeScript cache
59+
*.tsbuildinfo
60+
61+
# Optional npm cache directory
62+
.npm
63+
64+
# Optional eslint cache
65+
.eslintcache
66+
67+
# Optional stylelint cache
68+
.stylelintcache
69+
70+
# Microbundle cache
71+
.rpt2_cache/
72+
.rts2_cache_cjs/
73+
.rts2_cache_es/
74+
.rts2_cache_umd/
75+
76+
# Optional REPL history
77+
.node_repl_history
78+
79+
# Output of 'npm pack'
80+
*.tgz
81+
82+
# Yarn Integrity file
83+
.yarn-integrity
84+
85+
# dotenv environment variable files
86+
.env
87+
.env.development.local
88+
.env.test.local
89+
.env.production.local
90+
.env.local
91+
92+
# parcel-bundler cache (https://parceljs.org/)
93+
.cache
94+
.parcel-cache
95+
96+
# Next.js build output
97+
.next
98+
out
99+
100+
# Nuxt.js build / generate output
101+
.nuxt
102+
dist
103+
104+
# Gatsby files
105+
.cache/
106+
# Comment in the public line in if your project uses Gatsby and not Next.js
107+
# https://nextjs.org/blog/next-9-1#public-directory-support
108+
# public
109+
110+
# vuepress build output
111+
.vuepress/dist
112+
113+
# vuepress v2.x temp and cache directory
114+
.temp
115+
116+
# Docusaurus cache and generated files
117+
.docusaurus
118+
119+
# Serverless directories
120+
.serverless/
121+
122+
# FuseBox cache
123+
.fusebox/
124+
125+
# DynamoDB Local files
126+
.dynamodb/
127+
128+
# TernJS port file
129+
.tern-port
130+
131+
# Stores VSCode versions used for testing VSCode extensions
132+
.vscode-test
133+
134+
# yarn v2
135+
.yarn/cache
136+
.yarn/unplugged
137+
.yarn/build-state.yml
138+
.yarn/install-state.gz
139+
.pnp.*
140+
141+
### Node Patch ###
142+
# Serverless Webpack directories
143+
.webpack/
144+
145+
# Optional stylelint cache
146+
147+
# SvelteKit build / generate output
148+
.svelte-kit
149+
150+
### SAM ###
151+
# Ignore build directories for the AWS Serverless Application Model (SAM)
152+
# Info: https://aws.amazon.com/serverless/sam/
153+
# Docs: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-reference.html
154+
155+
**/.aws-sam
156+
157+
# End of https://www.toptal.com/developers/gitignore/api/node,sam
158+

‎lambda-debugging-sam-javascript/.vscode/launch.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"version": "0.2.0",
3+
"configurations": [
4+
{
5+
"name": "Node: Remote Attach",
6+
"type": "node",
7+
"request": "attach",
8+
"address": "127.0.0.1",
9+
"port": 6050,
10+
"localRoot": "${workspaceFolder}/hello-world",
11+
"remoteRoot": "/var/task/",
12+
}
13+
]
14+
}

‎lambda-debugging-sam-javascript/Makefile‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
.PHONY: usage install build build-docker build-local build-sam wait deploy deploy-aws deploy-sam invoke clean start stop ready test-ci
2+
3+
AWS_ENDPOINT_URL ?= http://localhost.localstack.cloud:4566
4+
AWS ?= AWS_ENDPOINT_URL=$(AWS_ENDPOINT_URL) \
5+
AWS_ACCESS_KEY_ID=test \
6+
AWS_SECRET_ACCESS_KEY=test \
7+
AWS_DEFAULT_REGION=us-east-1 \
8+
aws
9+
SAM ?= AWS_ENDPOINT_URL=$(AWS_ENDPOINT_URL) \
10+
AWS_ACCESS_KEY_ID=test \
11+
AWS_SECRET_ACCESS_KEY=test \
12+
AWS_DEFAULT_REGION=us-east-1 \
13+
sam
14+
FUNCTION_NAME ?= HelloWorldFunctionJavaScript
15+
LAMBDA_RUNTIME ?= nodejs22.x
16+
17+
# Changing architecture (arm64 or x86_64) requires rebuilding the Java package in Docker
18+
ARCH ?= x86_64
19+
DOCKER_PLATFORM ?= linux/$(ARCH)
20+
IMAGE ?= public.ecr.aws/sam/build-$(LAMBDA_RUNTIME):latest-$(ARCH)
21+
22+
all: usage
23+
24+
usage: ## Show this help
25+
@fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'
26+
27+
# TODO: figure out how to install the AWS CLI v2 in CI
28+
install: ## Install CLI dependencies
29+
@which aws || pip install awscli
30+
31+
build: build-local ## Build the Lambda function (default local)
32+
33+
# TODO: package runtime dependencies from package.json/node_modules
34+
# TODO: run tests before build
35+
build-docker: ## Build the Lambda function zip in Docker
36+
docker run --platform $(DOCKER_PLATFORM) --rm -v "$$(pwd)/hello-world:/app" $(IMAGE) bash -c "cd /app && zip -r hello-world-javascript.zip ."
37+
38+
# TODO: package runtime dependencies from package.json/node_modules
39+
# TODO: run tests before build
40+
build-local: ## Build the Lambda function zip locally (Node.js requires)
41+
cd hello-world && zip -r hello-world-javascript.zip .
42+
43+
build-sam: ## Build the Lambda function via AWS SAM
44+
$(SAM) build --use-container
45+
46+
wait: ## Wait until the Lambda function becomes ready to invoke
47+
$(AWS) lambda wait function-active-v2 --function-name $(FUNCTION_NAME)
48+
49+
deploy: deploy-aws ## Deploy the Lambda function (default AWS CLI)
50+
51+
deploy-aws: ## Deploy the Lambda function via AWS CLI
52+
$(AWS) lambda create-function \
53+
--function-name $(FUNCTION_NAME) \
54+
--runtime $(LAMBDA_RUNTIME) \
55+
--role arn:aws:iam::000000000000:role/lambda-role \
56+
--handler app.lambdaHandler \
57+
--zip-file fileb://hello-world/hello-world-javascript.zip \
58+
--timeout 2
59+
60+
deploy-sam: ## Deploy the Lambda function via AWS SAM CLI
61+
$(SAM) deploy
62+
63+
invoke: ## Invoke the Lambda function and show logs
64+
AWS_MAX_ATTEMPTS=1 $(AWS) lambda invoke --function-name $(FUNCTION_NAME) \
65+
--payload file://events/event.json \
66+
--cli-connect-timeout 3600 \
67+
--cli-read-timeout 3600 \
68+
--log-type Tail \
69+
response.json | jq .LogResult -r | base64 -d && cat response.json | jq -r .result
70+
71+
# TODO: avoid having the built zip file in the source directory
72+
clean: ## Clean the build directory
73+
rm -rf hello-world/hello-world-javascript.zip
74+
75+
start: ## Start LocalStack
76+
IMAGE_NAME=localstack/localstack-pro \
77+
LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} \
78+
LOCALSTACK_LAMBDA_DEBUG_MODE=1 \
79+
LOCALSTACK_LAMBDA_DEBUG_MODE_CONFIG_PATH=/tmp/lambda_debug_mode_config.yaml \
80+
localstack start --detached --volume ${PWD}/lambda_debug_mode_config.yaml:/tmp/lambda_debug_mode_config.yaml
81+
82+
stop: ## Stop LocalStack
83+
localstack stop
84+
85+
ready: ## Wait until LocalStack is running
86+
@echo Waiting on the LocalStack container...
87+
@localstack wait -t 30 && echo LocalStack is ready to use! || (echo Gave up waiting on LocalStack, exiting. && exit 1)
88+
89+
test-ci:
90+
make start install ready deploy wait invoke; return_code=`echo $$?`;\
91+
echo "Interactive debugging not tested in CI"; exit $$return_code;

‎lambda-debugging-sam-javascript/README.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Debug your JavaScript Lambda Function
2+
3+
This Hello World Lambda function written in JavaScript demonstrates how to use interactive breakpoint-debugging using LocalStack [Lambda Remote Debugging](https://docs.localstack.cloud/aws/tooling/lambda-tools/remote-debugging/).
4+
LocalStack automatically configures debugging and adjusts relevant timeouts.
5+
6+
We recommend the one-click setup using the AWS Toolkit for VS Code unless your advanced scenario requires Lambda Debug Mode (Preview).
7+
8+
> [!NOTE]
9+
> Check out our blog post [Developing with LocalStack using the AWS Toolkit for VS Code](#TODO-update-link)
10+
11+
## Prerequisites
12+
13+
* [Docker](https://www.docker.com/)
14+
* [VS Code](https://code.visualstudio.com/)
15+
* [LocalStack Toolkit for VS Code](https://marketplace.visualstudio.com/items?itemName=localstack.localstack) ≥ 1.2 installs [LocalStack](https://docs.localstack.cloud/aws/getting-started/installation/) ≥ 4.8
16+
* [AWS Toolkit for VS Code](https://marketplace.visualstudio.com/items?itemName=AmazonWebServices.aws-toolkit-vscode) ≥ 3.74
17+
* `make`
18+
* [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) or [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html)
19+
20+
## Starting Up
21+
22+
1. Execute the VS Code command "LocalStack: Run Setup Wizard" using the LocalStack Toolkit
23+
2. Start LocalStack by clicking on the LocalStack Toolkit status bar
24+
25+
## Deploying
26+
27+
1. Run `make build`
28+
2. Run `make deploy`
29+
30+
## Debugging
31+
32+
1. Open the **Remote invoke configuration** in the AWS Toolkit
33+
1. Open the AWS Toolkit extension
34+
2. Expand the AWS Explorer and Lambda node
35+
3. Navigate to the function you want to debug, then choose the Invoke remotely icon ▶️ from the context menu
36+
2. Select the **Remote debugging** check box to display the remote debugging properties
37+
3. Specify the Local Root Path to your local handler file.
38+
4. Set a breakpoint in your handler file by clicking in the gutter-margin
39+
5. Click the **Remote invoke** button to invoke the Lambda function
40+
41+
## Lambda Debug Mode (Preview, Pro)
42+
43+
### Starting Up
44+
45+
1. Start LocalStack with the following configuration:
46+
47+
```sh
48+
LOCALSTACK_IMAGE_NAME=localstack/localstack-pro \
49+
LOCALSTACK_LAMBDA_DEBUG_MODE=1 \
50+
LOCALSTACK_LAMBDA_DEBUG_MODE_CONFIG_PATH=/tmp/lambda_debug_mode_config.yaml \
51+
localstack start --volume $PWD/lambda_debug_mode_config.yaml:/tmp/lambda_debug_mode_config.yaml
52+
```
53+
54+
* `IMAGE_NAME=localstack/localstack-pro` ensures the Pro image is started
55+
* `LOCALSTACK_LAMBDA_DEBUG_MODE=1` adjusts timeouts
56+
* `LOCALSTACK_LAMBDA_DEBUG_MODE_CONFIG_PATH=/tmp/lambda_debug_mode_config.yaml` points to the config file for Lambda debug mode allowing for advanced configuration. It maps the Lambda function `arn:aws:lambda:us-east-1:000000000000:function:function-one` to port `6050`.
57+
* `--volume $PWD/lambda_debug_mode_config.yaml:/tmp/lambda_debug_mode_config.yaml` maps the Lambda debug configuration from the host into the LocalStack Docker container for hot-reloading configuration updates.
58+
59+
### Deploying
60+
61+
1. Run `make build` to build the Lambda ZIP package
62+
2. Run `make deploy` to deploy the Lambda function
63+
64+
### Debugging
65+
66+
1. Open the sample folder in VS Code to auto-detect `.vscode/launch.json`
67+
2. Set a breakpoint in the handler file `hello-world/app.mjs` by clicking in the gutter-margin
68+
3. Open the **Run and Debug** view in VS Code
69+
4. Run the **JavaScript: Remote Attach** task
70+
5. Run `make invoke` to invoke the Lambda function
71+
72+
## Troubleshooting
73+
74+
* Concurrent invokes are currently rejected with a `ResourceConflictException`.
75+
Upvote [this GitHub issue](https://github.com/localstack/localstack/issues/8522) if this affects you.
76+
77+
## License
78+
79+
The code in this sample is available under the Apache 2.0 license.

0 commit comments

Comments
 (0)