npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@bref.sh/local-api-gateway

v1.0.20

Published

Run API Gateway locally against your Docker Lambda functions

Downloads

114

Readme

This project lets you run HTTP Lambda applications locally.

Why

AWS Lambda containers (like Bref containers) can run locally, but they must be invoked via the Runtime Interface Emulator API, which is not practical. Here's an example with curl:

# Run your Lambda function
docker run --rm -it -p 8080:8080 -v $(PWD):/var/task bref/php-80-fpm public/index.php

# Call your function
curl -XPOST "http://localhost:8080/2015-03-31/functions/function/invocations" -d '{ http event goes here }'

That sucks 👎

If you use Lambda + API Gateway, you probably just want to access your app via HTTP… like any other HTTP application. This project does that.

Usage

This project publishes a bref/local-api-gateway Docker image.

This image creates a local API Gateway (i.e. HTTP server) that forwards HTTP requests to your Lambda function running in Docker.

The only thing it needs is a TARGET environment variable that contains the endpoint of your Lambda function: <host>:<port> (the default port of Lambda RIE is 8080).

Example

Example of docker-compose.yml:

version: "3.5"

services:
  
    # This container runs API Gateway locally
    web:
        image: bref/local-api-gateway
        ports: ['8000:8000']
        environment:
            # <host>:<port> -> the host here is "php" because that's the name of the second container
            TARGET: 'php:8080'
            
    # Example of container running AWS Lambda locally
    php:
        image: bref/php-80-fpm
        # The command should contain the Lambda handler
        command: public/index.php
        volumes:
            - .:/var/task:ro

If you need to change the default listening port, you can set the LISTEN_PORT environment variable value to whatever port you wish to use.

Static assets

If you want a quick and easy way to serve static assets, mount your files in the bref/local-api-gateway container and set the DOCUMENT_ROOT env var to the root of the assets.

DOCUMENT_ROOT is relative to /var/task (the root of the app), so it can contain . if your assets are in the root of the app.

For example:

services:
    web:
        image: bref/local-api-gateway
        ports: ['8000:8000']
        volumes:
            - .:/var/task:ro
        environment:
            TARGET: 'php:8080'
            DOCUMENT_ROOT: public
            
    # ...

FAQ

This vs Serverless Offline

Serverless Offline doesn't work with Bref, and doesn't work great if you run your Lambda in containers.

This project will be useful to you if you are in that case, or simply if you don't use Serverless Framework.

However, if you use Serverless Framework with JS, Python or another supported language, Serverless Offline is probably a better choice.

Does this support API Gateway routes?

No. To discover routes (and how they map to Lambda functions), we would have to parse CloudFormation templates/serverless.yml/CDK files/Terraform files/Pulumi files/etc. That's too much work for now :)

This project is mostly useful for people running web frameworks (like Laravel, Symfony, etc.) in Lambda, and don't use API Gateway's routing.

Does this support API Gateway features?

No, this is a very simple HTTP server. It does not support API Gateway features like CORS, authorizers, etc.

How are parallel requests handled?

The Lambda RIE does not support parallel requests. This project handles them by "queueing" requests. If a request is already being processed, the next request will be queued and processed when the first request is done.

This works up to 10 requests in parallel by default. You can change this limit by setting the DEV_MAX_REQUESTS_IN_PARALLEL environment variable.