Amazon Lambda function handler in Go - Amazon Lambda
NamingLambda function handler using structured typesUsing global state
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon Lambda function handler in Go

The Lambda function handler is the method in your function code that processes events. When your function is invoked, Lambda runs the handler method. Your function runs until the handler returns a response, exits, or times out.

A Lambda function written in Go is authored as a Go executable. In your Lambda function code, you need to include the github.com/aws/aws-lambda-go/lambda package, which implements the Lambda programming model for Go. In addition, you need to implement handler function code and a main() function. 

package main

import (
        "fmt"
        "context"
        "github.com/aws/aws-lambda-go/lambda"
)

type MyEvent struct {
        Name string `json:"name"`
}

func HandleRequest(ctx context.Context, name MyEvent) (string, error) {
        return fmt.Sprintf("Hello %s!", name.Name ), nil
}

func main() {
        lambda.Start(HandleRequest)
}

Note the following:

  • package main: In Go, the package containing func main() must always be named main.

  • import: Use this to include the libraries your Lambda function requires. In this instance, it includes:

    • context: Amazon Lambda context object in Go.

    • fmt: The Go Formatting object used to format the return value of your function.

    • github.com/aws/aws-lambda-go/lambda: As mentioned previously, implements the Lambda programming model for Go.

  • func HandleRequest(ctx context.Context, name MyEvent) (string, error): This is your Lambda handler signature and includes the code which will be executed. In addition, the parameters included denote the following:

    • ctx context.Context: Provides runtime information for your Lambda function invocation. ctx is the variable you declare to leverage the information available via Amazon Lambda context object in Go.

    • name MyEvent: An input type with a variable name of name whose value will be returned in the return statement.

    • string, error: Returns two values: string for success and standard error information. For more information on custom error handling, see Amazon Lambda function errors in Go.

    • return fmt.Sprintf("Hello %s!", name), nil: Simply returns a formatted "Hello" greeting with the name you supplied in the input event. nil indicates there were no errors and the function executed successfully.

  • func main(): The entry point that runs your Lambda function code. This is required.

    By adding lambda.Start(HandleRequest) between func main(){} code brackets, your Lambda function will be executed. Per Go language standards, the opening bracket, { must be placed directly at the end of the main function signature.

Naming

provided.al2 runtime

For Go functions that use the provided.al2 runtime in a .zip deployment package, the executable file that contains your function code must be named bootstrap. For Go functions that use the provided.al2 runtime in a container image, you can use any name for the executable file.

You can use any name for the handler. To reference the handler value in your code, you can use the _HANDLER environment variable.

go1.x runtime

For Go functions that use the go1.x runtime, the executable file and the handler can share any name. For example, if you set the value of the handler to Handler, Lambda will call the main() function in the Handler executable file.

To change the function handler name in the Lambda console, on the Runtime settings pane, choose Edit.

Lambda function handler using structured types

In the example above, the input type was a simple string. But you can also pass in structured events to your function handler:

package main
 
import (
        "fmt"
        "github.com/aws/aws-lambda-go/lambda"
)

type MyEvent struct {
        Name string `json:"What is your name?"`
        Age int     `json:"How old are you?"`
}
 
type MyResponse struct {
        Message string `json:"Answer:"`
}
 
func HandleLambdaEvent(event MyEvent) (MyResponse, error) {
        return MyResponse{Message: fmt.Sprintf("%s is %d years old!", event.Name, event.Age)}, nil
}
 
func main() {
        lambda.Start(HandleLambdaEvent)
}

Your request would then look like this:


# request
{
    "What is your name?": "Jim",
    "How old are you?": 33
}

And the response would look like this:


# response
{
    "Answer": "Jim is 33 years old!"
}

To be exported, field names in the event struct must be capitalized. For more information on handling events from Amazon event sources, see aws-lambda-go/events.

Valid handler signatures

You have several options when building a Lambda function handler in Go, but you must adhere to the following rules:

  • The handler must be a function.

  • The handler may take between 0 and 2 arguments. If there are two arguments, the first argument must implement context.Context.

  • The handler may return between 0 and 2 arguments. If there is a single return value, it must implement error. If there are two return values, the second value must implement error. For more information on implementing error-handling information, see Amazon Lambda function errors in Go.

The following lists valid handler signatures. TIn and TOut represent types compatible with the encoding/json standard library. For more information, see func Unmarshal to learn how these types are deserialized.

  • func ()
  • func () error
  • func (TIn) error
  • func () (TOut, error)
  • func (context.Context) error
  • func (context.Context, TIn) error
  • func (context.Context) (TOut, error)
  • func (context.Context, TIn) (TOut, error)

Using global state

You can declare and modify global variables that are independent of your Lambda function's handler code. In addition, your handler may declare an init function that is executed when your handler is loaded. This behaves the same in Amazon Lambda as it does in standard Go programs. A single instance of your Lambda function will never handle multiple events simultaneously.

package main
 
import (
        "log"
        "github.com/aws/aws-lambda-go/lambda"
        "github.com/aws/aws-sdk-go/aws/session"
        "github.com/aws/aws-sdk-go/service/s3"
        "github.com/aws/aws-sdk-go/aws"
)
 
var invokeCount = 0
var myObjects []*s3.Object
func init() {
        svc := s3.New(session.New())
        input := &s3.ListObjectsV2Input{
                Bucket: aws.String("examplebucket"),
        }
        result, _ := svc.ListObjectsV2(input)
        myObjects = result.Contents
}
 
func LambdaHandler() (int, error) {
        invokeCount = invokeCount + 1
        log.Print(myObjects)
        return invokeCount, nil
}
 
func main() {
        lambda.Start(LambdaHandler)
}