aws-sam-api-proxy 🚀

User and advocate of SAM? Improve development of API based Lambdas.

Execute your HTTP requests locally without hitting cold starts every time!

It's like running sam local start-api but keeping the containers (functions) around.

This tool will spin up a local server and proxy any incoming request to the expected lambda, here's how.

Features

• No cold starts on every request
  • in the first invocation a cold start is experienced, just like in the AWS environment
  • subsequent invocations are as fast as your code! 🏃‍♂️
• Context reutilization
• Always watching your distribution folder - rebuild your code and changes are propagated immediately
• Automatic discoverability of your Lambda functions
  • Global CodeUri, Runtime and Handlers are supported
  • Environment variables are passed through and can be overridden with --env-vars
  • All runtimes are supported
• Path parameters, querystring, body and headers are all passed through the request, with no changes
• Already supports Http Apis
• Supports local lambda function layers (ContentUri must be a relative path)
• Supports specifing your own docker socket path for added compatibility with Docker Desktop on Linux

Motivation

Developing AWS Lambdas and API Gateways locally is not usually the best experience.

I tend to develop with the help of unit tests but it just isn't enough. I always feel the need to make HTTP requests to properly test my template and code.

When I use sam local invoke or sam local start-api, even with the --skip-pull-image option, the cold starts on every request kills my mood and slows me down.

Another issue me and my team face, is that our APIs are behind a GraqhQL server. A query that should take less than a second to fulfil, takes about 6 to 7 seconds 🤨🔫

With this tool all this pain went away and I'm able to test my APIs much faster 😍

I hope somehow this tool is of any help to you. If you find a bug just open an issue or go ahead and fix it.

For more context you can read through aws-sam-cli/issues/239 and understand what led me to write this tool.

Requirements

The only dependency to use this CLI is docker. Make sure it's running.

CLI

Install

npm i aws-sam-api-proxy -g

Start API

Nice and easy:

cd ~/my-api
sam-proxy start my-api --port 3000

Or, with all the options available:

sam-proxy start my-api --port 3000 --base-path ~/my-api --template template.yaml --env-vars envVars.json --docker-network my_network --ref-overrides Env=dev,MyDynamoTable=http://localhost:8000 --log-level info --docker-socket-path /home/john-doe/.docker/desktop/docker.sock

Tearing down the house

For a specific API

sam-proxy teardown my-api

For all APIs

sam-proxy teardown-all

Environment Variables

Environment variables defined in your template.yaml either at the Function level or within Globals.Function are passed to the function containers. You can use --env-vars option to override variables pretty much as you would do using sam cli.

Overriding references

If the variable is a !Ref then the value will be resolved using the ref-overrides option passed to sam-proxy start.

Note that the references provided to sam-proxy start do not need to be defined inside the template's Parameters section. This allows you to fake resolution of other resources with !Ref. For example, passing --ref-overrides MyDynamoTable=http://localhost:8000 with a template as follows would allow your function to communicate with a local DynamoDB instance:

Resources:
  GetResources:
    Type: AWS::Serverless::Function
    Properties:
      Environment:
        Variables:
          DB_HOST: !Ref MyDynamoTable

  # Ignored by aws-sam-api-proxy:
  MyDynamoTable:
    Type: AWS::DynamoDB::Table
    # ...

More

sam-proxy --help

Running multiple APIs

If you want to run multiple APIs, the only detail to take in consideration is the port you choose to run your server on.

Why? All containers created by this tool will expose a port that is based on the server port.

Example:

Imagine your API has 4 endpoints and your server is running at port 3000.

4 containers are running, the following ports are being used: 3001, 3002, 3003 and 3004.

What you need to do, on the subsequent server, is to select an higher port. For this example, 3005 would be enough.

Template sample

My templates usually look something like this:

AWSTemplateFormatVersion: '2010-09-09'
Description: Resources API
Transform: AWS::Serverless-2016-10-31

Parameters:
  Env:
    Type: String
    AllowedValues:
      - dev
      - stg
      - prd

Globals:
  Function:
    Runtime: nodejs12.x
    MemorySize: 256
    Timeout: 10
    Environment:
      Variables:
        NODE_ENV: !Ref Env

Resources:
  GetResources:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: ./dist
      Handler: GetResourcesHandler.default
      Events:
        GetResourcesEvent:
          Type: Api
          Properties:
            Path: /resources
            Method: GET

Under the hood

Very succinctly, this tool does the following:

1. Parse your SAM template and your environment variables file if provided
2. Filter all functions triggered by Api or HttpApi events
3. Remove containers running for this API
4. Pull necessary docker images
5. Create and start containers for each Lambda function with the given environment variables
6. Spins up a server that acts as an API Gateway, proxying incoming requests to the expected containers

Keeping containers warm is possible due to the environment variable DOCKER_LAMBDA_STAY_OPEN that is given to the container on creation.

Logs

This tool will automatically log request details, duration and response status code.

If you want to check the logs of a function, just take a look at the container logs:

docker ps
docker logs get_resources_lambda

Credits

This tool wouldn't be possible without lambci/docker-lambda or dockerode. Thank you 🍻.

Roadmap

• Support JSON template
• Fill events missing data:
  • requestContext
  • multiValueHeaders
  • multiValueQueryStringParameters
  • cookies
  • stageVariables