aws-lambda-go-adapter

Description

This module makes it easy to test a Golang AWS Lambda outside of AWS, without needing Docker. Currently, only HTTP triggers are supported, but additional triggers may be supported in the future.

How it works

Lambda Function in AWS:

1. The main function calls the lambda.Start function, passing in the Handler function.
2. AWS Lambda invokes the Handler function when an HTTP request is received.
3. Alternatively, the main function can call lambda.StartWithOptions to enable graceful shutdown with an optional shutdown function(s).

Testing a Lambda Function outside of AWS:

1. The main function calls the httpadapter.Start function, passing in the Handler function and the port number to listen on.
2. The httpadapter listens for incoming HTTP requests on the specified port and invokes the Handler function when a request is received.
3. Alternatively, the main function can call httpadapter.StartWithOptions to enable graceful shutdown with an optional shutdown function(s).

Features

• Supports APIGatewayV2HTTP, APIGatewayProxy, and ALBTargetGroup events.
• Supports handler functions with and without context.Context parameters.
• Supports both values and pointers for handler function request events.
• Supports both values and pointers for handler function response events.

Installation

go get -u github.com/Evernorth/aws-lambda-go-adapter

Usage

Start

package main

import (
	"context"
	"github.com/Evernorth/aws-lambda-go-adapter/httpadapter"
	"github.com/Evernorth/aws-lambda-go-adapter/pkg/util"
	"github.com/aws/aws-lambda-go/events"
	"github.com/aws/aws-lambda-go/lambda"
	"net/http"
)

// Handler is the Lambda handler function.  It returns a 200 status code with a "Hello, World!" message for GET requests,
// and a 405 status code for all other requests.
func Handler(ctx context.Context, request events.APIGatewayV2HTTPRequest) (events.APIGatewayV2HTTPResponse, error) {

	if request.RequestContext.HTTP.Method == http.MethodGet {
		return events.APIGatewayV2HTTPResponse{
			StatusCode: http.StatusOK,
			Body:       "Hello, World!",
			Headers: map[string]string{
				"Content-Type": "text/html",
			},
		}, nil
	}

	return events.APIGatewayV2HTTPResponse{
		StatusCode: http.StatusMethodNotAllowed,
		Body:       "Method not allowed",
	}, nil
}

func main() {
	if util.IsLambdaRuntime() {
		lambda.Start(Handler)
	} else {
		httpadapter.Start(8080, Handler)
	}
}

StartWithOptions WithEnableSIGTERM

This is useful for application shutdown logic needed for a graceful shutdown. The httpadapter will mimic the AWS Lambda behavior of allowing ~500ms for shutdown before it is terminated.

package main

import (
	"context"
	"github.com/Evernorth/aws-lambda-go-adapter/httpadapter"
	"github.com/Evernorth/aws-lambda-go-adapter/pkg/util"
	"github.com/aws/aws-lambda-go/events"
	"github.com/aws/aws-lambda-go/lambda"
	"net/http"
)

// Handler is the Lambda handler function.  It returns a 200 status code with a "Hello, World!" message for GET requests,
// and a 405 status code for all other requests.
func Handler(ctx context.Context, request events.APIGatewayV2HTTPRequest) (events.APIGatewayV2HTTPResponse, error) {

	if request.RequestContext.HTTP.Method == http.MethodGet {
		return events.APIGatewayV2HTTPResponse{
			StatusCode: http.StatusOK,
			Body:       "Hello, World!",
			Headers: map[string]string{
				"Content-Type": "text/html",
			},
		}, nil
	}

	return events.APIGatewayV2HTTPResponse{
		StatusCode: http.StatusMethodNotAllowed,
		Body:       "Method not allowed",
	}, nil
}

func shutdown() {
    // Perform any necessary cleanup here, such as closing database connections or releasing resources.
    // This function is called during graceful shutdown.
}

func main() {
	if util.IsLambdaRuntime() { 
	    // Start AWS Lambda function with SIGTERM support for graceful shutdown. 
	    // App shutdown logic has ~500ms to complete before it's terminated with a Lambda SIGKILL 
	    lambda.StartWithOptions(Handler, 
	        lambda.WithEnableSIGTERM(shutdown))
	} else {
	    // Start HTTP server with SIGTERM support for graceful shutdown.
	    // App shutdown logic has ~500ms to complete before it's terminated with a "SIGKILL" panic
	    httpadapter.StartWithOptions(8080, Handler,
	        httpadapter.WithEnableSIGTERM(shutdown))
	}
}

Dependencies

See the go.mod file.

Support

If you have questions, concerns, bug reports, etc. See CONTRIBUTING.

License

aws-lambda-go-adapter is open source software released under the Apache 2.0 license.

Original Contributors

• Steve Sefton, Evernorth
• Ben Lilley, Evernorth