website-api

.
├── .aws-sam                    <-- Packaged SAM function [temporary]
├── .backend-testing-env        <-- Enviornment file for testing lambda functions locally with testLocalScript.js [temporary]
├── apply                       <-- Source code for the apply Lambda function
│   └── index.js                <-- Lambda function code
│   └── package.json            <-- Lists Node.js module dependencies
│   └── package-lock.json       <-- Locks down specific Node.js module versions
├── events                      <-- Sample events
├── specs                       <-- Unit tests
├── upload                      <-- Source code for the upload Lambda function
│   └── index.js                <-- Lambda function code
│   └── package.json            <-- Lists Node.js module dependencies
│   └── package-lock.json       <-- Locks down specific Node.js module versions
├── README.MD                   <-- This instructions file
├── buildspec.yml               <-- CodeBuild specification
├── env.json                    <-- Environment vars used when functions are invoked locally
├── package.json                <-- Defines development and deployment scripts
├── packaged.yaml               <-- Packaged SAM template [temporary]
├── testLocalScript.js          <-- Script to test Lambda functions locally without Docker
├── template.yaml               <-- SAM template

Requirements

• AWS CLI installed and configured with administrative privileges
• Install Docker
• Install AWS SAM CLI
• Install NodeJS 18.x

Setup process

Local development

Invoking function locally using a local sample payload

sam local invoke UploadFunction --event samples/upload.json

Invoking function locally through local API Gateway

sam local start-api

If the previous command ran successfully you should now be able to hit the following local endpoint to invoke your function http://localhost:3000/upload

SAM CLI is used to emulate both Lambda and API Gateway locally and uses our template.yaml to understand how to bootstrap this environment (runtime, where the source code is, etc.) - The following excerpt is what the CLI will read in order to initialize an API and its routes:

---
Events:
  postProxy:
    Type: Api # More info about API Event Source: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#api
    Properties:
    Path: /{proxy+}
    Method: put

Packaging and deployment

AWS Lambda NodeJS runtime requires a flat folder with all dependencies including the application. SAM will use CodeUri property to know where to look up for both application and dependencies:

...
    UploadFunction:
        Type: AWS::Serverless::Function
        Properties:
            CodeUri: upload/
            ...

Firstly, we need an S3 bucket where we can upload our Lambda functions packaged as ZIP before we deploy anything - If you don't have a S3 bucket to store code artifacts then this is a good time to create one:

aws s3 mb s3://<REPLACE_THIS_WITH_YOUR_S3_BUCKET_NAME>

Next, run the following command to package our Lambda function to S3:

sam package \
    --output-template-file packaged.yaml \
    --s3-bucket <REPLACE_THIS_WITH_YOUR_S3_BUCKET_NAME>

Next, the following command will create a Cloudformation Stack and deploy your SAM resources.

sam deploy \
    --template-file packaged.yaml \
    --stack-name <REPLACE_WITH_YOUR_STACK_NAME> \
    --capabilities CAPABILITY_IAM

See Serverless Application Model (SAM) HOWTO Guide for more details in how to get started.

After deployment is complete you can run the following command to retrieve the API Gateway Endpoint URL:

aws cloudformation describe-stacks \
    --stack-name <REPLACE_WITH_YOUR_STACK_NAME> \
    --query 'Stacks[].Outputs[?OutputKey==`UploadApi`]' \
    --output table

Fetch, tail, and filter Lambda function logs

To simplify troubleshooting, SAM CLI has a command called sam logs. sam logs lets you fetch logs generated by your Lambda function from the command line. In addition to printing the logs on the terminal, this command has several nifty features to help you quickly find the bug.

NOTE: This command works for all AWS Lambda functions; not just the ones you deploy using SAM.

sam logs -n UploadFunction --stack-name <REPLACE_WITH_YOUR_STACK_NAME> --tail

You can find more information and examples about filtering Lambda function logs in the SAM CLI Documentation.

Testing Lambda Functions Locally without Docker

To test your Lambda function locally, first ensure that your .backend-testing-env file is in the CloudFormation folder.

If you do not have a .backend--testing-env file. Run the following command:

npm run download:backend-testing:env

In the main directory there should be a testLocalScript.js file. This file contains a script that helps test Lambda functions locally.

You can see all the current lambda function tests by running command:

npm run testLambdaLocal

To test a specific lambda function run the command:

npm run testLambdaLocal {LambdaOption}

Add a new test

1. In testLocalScript.js file in the Lambdas section add a new object key in the lambdas JSON object.

• For that new key create a JSON object with 2 key pairs: function and event.
• function should be set to the pathTo the file location of the Lambda function you want to test
• event should be set a String value with the value of the path location to the event file that you want to test against your Lambda function.

Example:

const lambdas = {
  template: { function: pathTo('lambda-template/app.js'), event: 'lambda-template/event.json' }
};

To run the template example the command would be:

npm run testLambdaLocal template

Testing

We use jasmine for testing our code and it is already added in package.json under scripts, so that we can simply run the following command to run our tests:

cd upload
npm ci
npm run test

Cleanup

To delete your serverless application, use the following AWS CLI Command:

aws cloudformation delete-stack --stack-name <REPLACE_WITH_YOUR_STACK_NAME>

Bringing to the next level

Here are a few things you can try to get more acquainted with building serverless applications using SAM:

Learn how SAM Build can help you with dependencies

• Build the project with sam build --use-container
• Invoke with sam local invoke UploadFunction --event samples/upload.json
• Update tests

Create an additional API resource

• Create a catch all resource (e.g. /upload/{proxy+}) and return the name requested through this new path
• Update tests

Step-through debugging

• Enable step-through debugging docs for supported runtimes

Next, you can use AWS Serverless Application Repository to deploy ready to use Apps that go beyond hello world samples and learn how authors developed their applications: AWS Serverless Application Repository main page

Appendix

Building the project

AWS Lambda requires a flat folder with the application as well as its dependencies in a node_modules folder. When you make changes to your source code or dependency manifest, run the following command to build your project local testing and deployment:

sam build

If your dependencies contain native modules that need to be compiled specifically for the operating system running on AWS Lambda, use this command to build inside a Lambda-like Docker container instead:

sam build --use-container

By default, this command writes built artifacts to .aws-sam/build folder.

SAM and AWS CLI commands

All commands used throughout this document

# Invoke function locally with event.json as an input
sam local invoke UploadFunction --event events/upload.json

# Run API Gateway locally
sam local start-api

# Create S3 bucket
aws s3 mb s3://<REPLACE_THIS_WITH_YOUR_S3_BUCKET_NAME>

# Package Lambda function defined locally and upload to S3 as an artifact
sam package \
    --output-template-file packaged.yaml \
    --s3-bucket <REPLACE_THIS_WITH_YOUR_S3_BUCKET_NAME>

# Deploy SAM template as a CloudFormation stack
sam deploy \
    --template-file packaged.yaml \
    --stack-name <REPLACE_WITH_YOUR_STACK_NAME> \
    --capabilities CAPABILITY_IAM

# Describe Output section of CloudFormation stack previously created
aws cloudformation describe-stacks \
    --stack-name <REPLACE_WITH_YOUR_STACK_NAME> \
    --query 'Stacks[].Outputs[?OutputKey==`UploadApi`]' \
    --output table

# Tail Lambda function Logs using Logical name defined in SAM Template
sam logs -n UploadFunction --stack-name <REPLACE_WITH_YOUR_STACK_NAME> --tail

NOTE: Alternatively this could be part of package.json scripts section.

Documentation

aws-lambda-multipart-parser

https://www.npmjs.com/package/aws-lambda-multipart-parser

AWS_SDK:

https://docs.aws.amazon.com/sdk-for-javascript/

we're currently using version 2

Cloudformation:

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html

Lodash:

https://lodash.com/

DayJS:

https://day.js.org/docs/en/installation/installation