lambdah

lambdah provides a useful abstraction layer over AWS Lambda functions written in Go.

Features:

A simple interface for writing lambda functions of all types
Extensible middleware framework
Data binding for JSON payloads
Highly customisable
Optional logging and tracing tools via middleware

Installation

lambdah is available as a Go module - import any package under github.com/webbgeorge/lambdah in your project to get started.

Getting started

lambdah has handlers for many types of event. Here are two example handlers for API Gateway Proxy Requests and SQS Messages.

API Gateway Proxy request handler

package main

import (
	"net/http"

	lambdah "github.com/webbgeorge/lambdah/api_gateway_proxy"
)

func main() {
	lambdah.HandlerFunc(handler).Start()
}

// handle http request via API Gateway
func handler(c *lambdah.Context) error {
	return c.String(http.StatusOK, "Hello world!")
}

SQS message handler

package main

import (
	"fmt"

	lambdah "github.com/webbgeorge/lambdah/sqs"
)

func main() {
	lambdah.HandlerFunc(handler).Start()
}

// handle SQS message
func handler(c *lambdah.Context) error {
	// Unmarshal JSON message data into a struct
	var data messageData
	err := c.Bind(&data)
	if err != nil {
		return err
	}

	// just log the name to CloudWatch Logs (via stdout) for the example
	fmt.Println(data.Name)

	return nil
}

type messageData struct {
	Greeting string `json:"greeting"`
	Name     string `json:"name"`
}

More examples

Handler type | Example ----------------- | ----------------- api_gateway_proxy | basic api_gateway_proxy | custom error handler api_gateway_proxy | apitest cloudwatch_events | basic cloudwatch_events | middleware dynamodb | basic dynamodb | middleware generic | basic generic | middleware s3 | basic s3 | middleware sns | basic sns | middleware sqs | basic sqs | middleware

Concepts

Middleware

lambdah provides a middleware system to allow extending the functionality of its handlers. Using middleware on any handler is completely optional.

Each handler includes some default middleware that you can choose to use or not. This includes a CorrelationIDMiddleware and a LoggerMiddleware for all handlers. Some handlers have additional default middleware, such as the api_gateway_proxy.ErrorHandlerMiddleware middleware.

In addition to default middleware, custom middleware can be created using a simple API, described below.

Using middleware

Here is the same simple API Gateway Proxy handler from above, with the addition of two middleware.

package main

import (
	"net/http"
	"os"

	lambdah "github.com/webbgeorge/lambdah/api_gateway_proxy"
)

func main() {
	lambdah.
		HandlerFunc(handler).
		Middleware(
			lambdah.CorrelationIDMiddleware(),
			lambdah.LoggerMiddleware(os.Stdout, nil),
		).
		Start()
}

// handle http request via API Gateway
func handler(c *lambdah.Context) error {
	return c.String(http.StatusOK, "Hello world!")
}

Custom middleware

Here is a simple example of a custom middleware for the API Gateway Proxy handler.

package main

import (
	"fmt"

	lambdah "github.com/webbgeorge/lambdah/api_gateway_proxy"
)

// function which returns our custom middleware
func MyCustomMiddleware() lambdah.Middleware {
	return func(h lambdah.HandlerFunc) lambdah.HandlerFunc {
		return func(c *lambdah.Context) error {
			// just log to CloudWatch Logs (via stdout) for the example
			fmt.Println("middleware triggered")
			return h(c)
		}
	}
}

Default middleware

Handler | Default middleware ----------------- | ------------------ api_gateway_proxy | ErrorHandlerMiddleware, CorrelationIDMiddleware, LoggerMiddleware cloudwatch_events | CorrelationIDMiddleware, LoggerMiddleware dynamodb | CorrelationIDMiddleware, LoggerMiddleware generic | CorrelationIDMiddleware, LoggerMiddleware s3 | CorrelationIDMiddleware, LoggerMiddleware sns | CorrelationIDMiddleware, LoggerMiddleware sqs | CorrelationIDMiddleware, LoggerMiddleware

Binding data

Many of the handler types allow you to bind payload data into a Go data structure.

This includes:

API Gateway Proxy request body (from JSON)
CloudWatch event detail (from JSON)
DynamoDB event images (from DynamoDB attribute map)
Generic event payload (from JSON)
SNS event data (from JSON)
SQS message data (from JSON)

For example, here is an example SNS event handler which binds JSON data:

package main

import (
	"fmt"

	lambdah "github.com/webbgeorge/lambdah/sns"
)

func main() {
	lambdah.HandlerFunc(handler).Start()
}

// handle SNS event
func handler(c *lambdah.Context) error {
	// Unmarshal JSON message data into a struct
	var data messageData
	err := c.Bind(&data)
	if err != nil {
		return err
	}

	// just log the name to CloudWatch Logs (via stdout) for the example
	fmt.Println(data.Name)

	return nil
}

type messageData struct {
	Greeting string `json:"greeting"`
	Name     string `json:"name"`
}

Logging

lambdah provides some built-in logging support using middleware. Logging can be an opinionated matter, so using this is completely optional.

To enable a logger on any type of handler, attach its LoggerMiddleware. This attaches a zerolog logger to the context of each event. Two arguments are required to use the logger middleware:

an io.Writer to write log messages to
a map[string]string of fields to add to the log data (set to nil if not wanted)

lambdah.
	HandlerFunc(handler).
	Middleware(
		lambdah.LoggerMiddleware(os.Stdout, map[string]string{"logFieldOne": "valueOne"}),
	).
	Start()

The logger middleware will, by default, log the status of each processed event with some basic details about the event. The logger can also be accessed within your handlers and custom middleware.

func handler(c *lambdah.Context) error {
	logger := log.LoggerFromContext(c.Context)
	logger.Info().Msg("hello logs")
	return c.String(http.StatusOK, "Hello world!")
}

Correlation IDs

lambdah provides an optional CorrelationIDMiddleware for all of its handlers. This middleware retrieves or creates a Correlation ID, which is often used for tracing requests through distributed systems in logs. This correlation ID is always a v4 UUID e.g. 9187bcbb-052b-45e5-bffa-99f323a8aa71.

When used in conjunction with the LoggerMiddleware, each log message includes the Correlation ID. Note that the CorrelationIDMiddleware must be included before the LoggerMiddleware.

The Correlation ID can also be accessed from within handlers and custom middleware:

func handler(c *lambdah.Context) error {
	cid := log.CorrelationIDFromContext(c.Context)
	// log correlation id for example
	fmt.Println(cid)
	return c.String(http.StatusOK, "Hello world!")
}

Source of Correlation ID

The handler sources or creates the Correlation ID in different ways depending on its type.

Handler | Correlation ID Source ----------------- | ------------------ api_gateway_proxy | Correlation-Id request header if present, otherwise is created by lambdah cloudwatch_events | CloudWatch Event ID dynamodb | created by lambdah generic | created by lambdah s3 | created by lambdah sns | correlation_id SNS message attribute if present, otherwise is created by lambdah sqs | correlation_id SQS message attribute if present, otherwise is created by lambdah

Contributing

See CONTRIBUTING.md

Lambdah

Install / Use

README