eawsy/aws-lambda-go-shim
Author your AWS Lambda function code in Go.
AWS Lambda lets you run code without provisioning or managing servers. For now, you can author your Lambda function code in Node.js, Java, C# and Python, but not in Go. This project fills the gap.
Table of Contents
Quick Hands-On
Dependencies
go get -u -d github.com/eawsy/aws-lambda-go-core/...
docker pull eawsy/aws-lambda-go-shim
wget -O Makefile https://github.com/eawsy/aws-lambda-go-shim/raw/master/src/Makefile.example
Create
package main
// /* Required, but no C code needed. */
import "C"
import (
"encoding/json"
"github.com/eawsy/aws-lambda-go-core/service/lambda/runtime"
)
func Handle(evt json.RawMessage, ctx *runtime.Context) (interface{}, error) {
return "Hello, World!", nil
}
Build
make
Deploy
aws lambda create-function \
--role arn:aws:iam::AWS_ACCOUNT_NUMBER:role/lambda_basic_execution \
--function-name preview-go \
--zip-file fileb://package.zip \
--runtime python2.7 \
--handler handler.Handle
Invoke
Programming Model
Although not required, we recommand you review AWS Lambda Developer Guide first.
This section explains how common programming patterns and core concepts apply when authoring AWS Lambda function code in Go.
Handler
The handler is an exported function in your code, that AWS Lambda invokes when executing your code.
func Handle(evt json.RawMessage, ctx *runtime.Context) (interface{}, error) {
...
}
AWS Lambda uses
evtparameter to pass in event data to the handler. An automatic JSON unmarshalling is performed before passing in the data, so that you can use any valid Go type. Refer to eawsy/aws-lambda-go-event for AWS services event definitions.func Handle(evt *MyCustomType, ctx *runtime.Context) (interface{}, error) { ... }
AWS Lambda uses
ctxparameter to provide runtime information to the handler. Refer to eawsy/aws-lambda-go-core for more details.The handler can either return any valid Go value or an error. What happens to the result depends on the invocation type. In a synchronous execution, AWS Lambda returns the result, serialized in JSON, to the client.
func Handle(evt json.RawMessage, ctx *runtime.Context) (*MyCustomType, error) { ... }
Context
The context is an object containing runtime information, that AWS Lambda passes as the second parameter of the handler when executing your code. Refer to eawsy/aws-lambda-go-core for more details.
RemainingTimeInMillis()returns the remaining execution time, in milliseconds, until Lambda terminates the function.FunctionNameis the name of the Lambda function that is executing.FunctionVersionis the version of the Lambda function that is executing. If an alias is used to invoke the function, then it will be the version the alias points to.InvokedFunctionARNis the ARN used to invoke this function. It can be function ARN or alias ARN. An unqualified ARN executes the $LATEST version and aliases execute the function version it is pointing to.MemoryLimitInMBis the memory limit, in MB, you configured for the Lambda function.AWSRequestIDis the AWS request ID associated with the request. This is the ID returned to the client. If Lambda retries the invocation (in case of execution failure), the AWS request ID remains the same.LogGroupNameis the name of the CloudWatch log group where you can find logs written by your Lambda function.LogStreamNameis the name of the CloudWatch log stream where you can find logs written by your Lambda function. The log stream may or may not change for each invocation of the Lambda function.Identityis the information about the Amazon Cognito identity provider when invoked through the AWS Mobile SDK.ClientContextis the information about the client application and device when invoked through the AWS Mobile SDK.
Logging
The handler can contain logging statements by using the standard Go fmt or log packages. Both fmt and log functions write logs to AWS CloudWatch Logs but the log functions write additional information to each log entry, such as timestamp and request id.
fmt.Print[f|ln]func Handle(evt json.RawMessage, ctx *runtime.Context) (interface{}, error) { fmt.Println("Hello, World!") return nil, nil } // Hello, World!
log.Print[f|ln],log.Fatal[f|ln],log.Panic[f|ln]func Handle(evt json.RawMessage, ctx *runtime.Context) (interface{}, error) { log.Println("Hello, World!") return nil, nil } // 2017-01-01T00:00:00.000Z 12ad5f64-d111-11e6-b4b4-b757a100146b Hello, World!
Errors
The handler can return any standard Go error. AWS Lambda recognizes the error and serializes its information into JSON and returns it to the client.
func Handle(evt json.RawMessage, ctx *runtime.Context) (interface{}, error) {
return nil, errors.New("Oh, Snap!")
}
// {
// "errorMessage": "Oh, Snap!"
// }
It is worth noting that if the handler panics, the returned error will be generic but the stack trace will be logged.
func Handle(evt json.RawMessage, ctx *runtime.Context) (interface{}, error) {
panic("Oh, Snap!")
return nil, nil
}
// {
// "errorMessage": "RequestId: 7322cf9e-d10d-11e6-ad86-d3cd48e293cf Process exited before completing request"
// }
Deployment Package
Although not required, we recommand you review AWS Lambda Developer Guide first.
This section explains how to build AWS Lambda function code in Go, create a Zip package and configure deployment.
To streamline common use cases, we provide an example Makefile with two environment variables (HANDLER and PACKAGE) to control the name of the generated binary and package. Feel free to customize build flags, append static assets to the package, etc.
Default Configuration
By default, HANDLER is set to handler and PACKAGE to package.
Create
func Handle...
Build
make # handler.so # package.zip
Deployment
- Runtime: Python 2.7
- Handler: handler.Handle
Custom Handler
By setting HANDLER to foo, the generated binary becomes foo.so.
Create
func Bar...
Build
HANDLER=foo make # foo.so # package.zip
Deployment
- Runtime: Python 2.7
- Handler: foo.Bar
Custom Package
By setting PACKAGE to baz, the generated package becomes baz.zip.
Create
func Handle...
Build
PACKAGE=baz make # handler.so # baz.zip
Deployment
- Runtime: Python 2.7
- Handler: handler.Handle
About
This project is maintained and funded by Alsanium, SAS.
We
Contact
We want to make it easy for you, users and contributers, to talk with us and connect with each others, to share ideas, solve problems and make help this project awesome. Here are the main channels we're running currently and we'd love to hear from you on them.
Follow and chat with us on Twitter.
Share stories!
Gitter
This is for all of you. Users, developers and curious. You can find help, links, questions and answers from all the community including the core team.
Ask questions!
GitHub
You are invited to contribute new features, fixes, or updates, large or small; we are always thrilled to receive pull requests, and do our best to process them as fast as we can.
Before you start to code, we recommend discussing your plans through the eawsy/bavardage channel, especially for more ambitious contributions. This gives other contributors a chance to point you in the right direction, give you feedback on your design, and help you find out if someone else is working on the same thing.
Write code!
License
This product is licensed to you under the Apache License, Version 2.0 (the "License"); you may not use this product except in compliance with the License. See LICENSE and NOTICE for more information.
Trademark
Alsanium, eawsy, the "Created by eawsy" logo, and the "eawsy" logo are trademarks of Alsanium, SAS. or its affiliates in France and/or other countries.
Amazon Web Services, the "Powered by Amazon Web Services" logo, and AWS Lambda are trademarks of Amazon.com, Inc. or its affiliates in the United States and/or other countries.
