lambda_router

Documentation

Overview

Package lambda_router is a simple-to-use library for writing AWS Lambda functions in Go that listen to events of type API Gateway Proxy Req (represented by the `events.APIGatewayProxyRequest` type of the github.com/aws-lambda-go/events package).

The library allows creating functions that can match reqs based on their URI, just like an HTTP server that uses the standard https://golang.org/pkg/net/http/#ServeMux (or any other community-built routing library such as https://github.com/julienschmidt/httprouter or https://github.com/go-chi/chi) would. The interface provided by the library is very similar to these libraries and should be familiar to anyone who has written HTTP applications in Go.

Use Case

When building large cloud-native applications, there's a certain balance to strike when it comes to deployment of APIs. On one side of the scale, each API endpoint has its own lambda function. This provides the greatest flexibility, but is extremely difficult to maintain. On the other side of the scale, there can be one lambda function for the entire API. This provides the least flexibility, but is the easiest to maintain. Both are probably not a good idea.

With `lmdrouter`, one can create small lambda functions for different aspects of the API. For example, if your application model contains multiple domains (e.g. articles, authors, topics, etc...), you can create one lambda function for each domain, and deploy these independently (e.g. everything below "/api/articles" is one lambda function, everything below "/api/authors" is another function). This is also useful for applications where different teams are in charge of different parts of the API.

Features

* Supports all HTTP methods.

* Supports middleware functions at a global and per-resource level.

* Supports path parameters with a simple ":<name>" format (e.g. "/posts/:id").

* Provides ability to automatically "unmarshal" an API Gateway req to an arbitrary Go struct, with data coming either from path and query string parameters, or from the req body (only JSON reqs are currently supported). See the documentation for the `UnmarshalReq` function for more information.

* Provides the ability to automatically "marshal" responses of any type to an API Gateway response (only JSON responses are currently generated). See the CustomRes function for more information.

• Implements net/http.Handler for local development and general usage outside an AWS Lambda environment.

Index

• Constants
• Variables
• func CustomRes(httpStatus int, headers map[string]string, data interface{}) (events.APIGatewayProxyResponse, error)
• func EmptyRes() (events.APIGatewayProxyResponse, error)
• func ErrorRes(err error) (events.APIGatewayProxyResponse, error)
• func FileB64Res(contentType string, headers map[string]string, fileBytes []byte) (events.APIGatewayProxyResponse, error)
• func FileRes(contentType string, headers map[string]string, fileBytes []byte) (events.APIGatewayProxyResponse, error)
• func MarshalReq(input interface{}) events.APIGatewayProxyRequest
• func StatusAndErrorRes(httpStatus int, err error) (events.APIGatewayProxyResponse, error)
• func SuccessRes(data interface{}) (events.APIGatewayProxyResponse, error)
• func UnmarshalReq(req events.APIGatewayProxyRequest, body bool, target interface{}) error
• func UnmarshalRes(res events.APIGatewayProxyResponse, target interface{}) error
• type HTTPError
  • func (err HTTPError) Error() string
• type Handler
• type Middleware
• type Router
  • func NewRouter(basePath string, middleware ...Middleware) (l *Router)
  • func (l *Router) Handler(ctx context.Context, req events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error)
  • func (l *Router) Route(method, path string, handler Handler, middleware ...Middleware)
  • func (l *Router) ServeHTTP(w http.ResponseWriter, r *http.Request)

Constants

const CORSHeadersEnvKey = "LAMBDA_JWT_ROUTER_CORS_HEADERS"

const CORSHeadersHeaderKey = "Access-Control-Allow-Headers"

const CORSMethodsEnvKey = "LAMBDA_JWT_ROUTER_CORS_METHODS"

const CORSMethodsHeaderKey = "Access-Control-Allow-Methods"

const CORSOriginEnvKey = "LAMBDA_JWT_ROUTER_CORS_ORIGIN"

const CORSOriginHeaderKey = "Access-Control-Allow-Origin"

const ContentTypeKey = "Content-Type"

Variables

var ExposeServerErrors = true

ExposeServerErrors is a boolean indicating whether the ErrorRes function should expose errors of status code 500 or above to clients. If false, the name of the status code is used as the error message instead.

Functions

func CustomRes

func CustomRes(httpStatus int, headers map[string]string, data interface{}) (
	events.APIGatewayProxyResponse,
	error,
)

CustomRes generated an events.APIGatewayProxyResponse object that can be directly returned via the lambda's handler function. It receives an HTTP status code for the response, a map of HTTP headers (can be empty or nil), and a value (probably a struct) representing the response body. This value will be marshaled to JSON (currently without base 64 encoding).

func EmptyRes

func EmptyRes() (events.APIGatewayProxyResponse, error)

EmptyRes returns a simple empty events.APIGatewayProxyResponse with http.StatusOK

func ErrorRes

func ErrorRes(err error) (events.APIGatewayProxyResponse, error)

ErrorRes generates an events.APIGatewayProxyResponse from an error value. If the error is an HTTPError, the response's status code will be taken from the error. Otherwise, the error is assumed to be 500 Internal Server Error. Regardless, all errors will generate a JSON response in the format `{ "code": 500, "error": "something failed" }` This format cannot currently be changed. If you do not wish to expose server errors (i.e. errors whose status code is 500 or above), set the ExposeServerErrors global variable to false.

func FileB64Res

func FileB64Res(contentType string, headers map[string]string, fileBytes []byte) (events.APIGatewayProxyResponse, error)

FileB64Res generates a new events.APIGatewayProxyResponse with the ContentTypeKey header set appropriately, the file bytes encoded to base64, and the http status set to http.StatusOK

func FileRes

func FileRes(contentType string, headers map[string]string, fileBytes []byte) (events.APIGatewayProxyResponse, error)

FileRes generates a new events.APIGatewayProxyResponse with the ContentTypeKey header set appropriately, the file bytes added to the response body, and the http status set to http.StatusOK

func MarshalReq

func MarshalReq(input interface{}) events.APIGatewayProxyRequest

MarshalReq will take an interface input, marshal it to JSON, and add the JSON as a string to the events.APIGatewayProxyRequest body field before returning.

func StatusAndErrorRes

func StatusAndErrorRes(httpStatus int, err error) (events.APIGatewayProxyResponse, error)

StatusAndErrorRes generates a custom error return response with the given http status code and error. Setting ExposeServerErrors to false will prevent leaking data to clients.

func SuccessRes

func SuccessRes(data interface{}) (events.APIGatewayProxyResponse, error)

SuccessRes wraps CustomRes assuming a http.StatusOK status code and no custom headers to return. This was such a common use case I felt it necessary to create a wrapper to make everyone's life easier.

func UnmarshalReq

func UnmarshalReq(req events.APIGatewayProxyRequest, body bool, target interface{}) error

UnmarshalReq "fills" out a target Go struct with data from the req. If body is true, then the req body is assumed to be JSON and simply unmarshalled into the target (taking into account that the req body may be base-64 encoded). After that, or if body is false, the function will traverse the exported fields of the target struct, and fill those that include the "lambda" struct tag with values taken from the request's query string parameters, path parameters and headers, according to the field's struct tag definition. This means a struct value can be filled with data from the body, the path, the query string and the headers at the same time.

Field types are currently limited to string, all integer types, all unsigned integer types, all float types, booleans, slices of the aforementioned types and pointers of these types.

Note that custom types that alias any of the aforementioned types are also accepted and the appropriate constant values will be generated. Boolean fields accept (in a case-insensitive way) the values "1", "true", "on" and "enabled". Any other value is considered false.

Example struct (no body):

type ListPostsInput struct {
    ID          uint64   `lambda:"path.id"`
    Page        uint64   `lambda:"query.page"`
    PageSize    uint64   `lambda:"query.page_size"`
    Search      string   `lambda:"query.search"`
    ShowDrafts  bool     `lambda:"query.show_hidden"`
    Languages   []string `lambda:"header.Accept-Language"`
}

Example struct (JSON body):

type UpdatePostInput struct {
    ID          uint64   `lambda:"path.id"`
    Author      string   `lambda:"header.Author"`
    Title       string   `json:"title"`
    Content     string   `json:"content"`
}

func UnmarshalRes

func UnmarshalRes(res events.APIGatewayProxyResponse, target interface{}) error

UnmarshalRes should generally be used only when testing as normally you return the response directly to the caller and won't need to Unmarshal it. However, if you are testing locally then it will help you extract the response body of a lambda request and marshal it to an object.

Types

type HTTPError

type HTTPError struct {
	Status  int    `json:"status"`
	Message string `json:"message"`
}

HTTPError is a generic struct type for JSON error responses. It allows the library to assign an HTTP status code for the errors returned by its various functions.

func (HTTPError) Error

func (err HTTPError) Error() string

Error returns a string representation of the HTTPError instance.

type Handler

type Handler func(context.Context, events.APIGatewayProxyRequest) (
	events.APIGatewayProxyResponse,
	error,
)

Handler is a req handler function. It receives a context, and the API Gateway's proxy req object, and returns a proxy response object and an error.

Example:

 func listSomethings(ctx context.Context, req events.APIGatewayProxyRequest) (
     res events.APIGatewayProxyResponse,
     err error,
 ) {
     // parse input
     var input listSomethingsInput
     err = lmdrouter.UnmarshalReq(req, false, &input)
     if err != nil {
         return lmdrouter.ErrorRes(err)
     }

     // call some business logic that generates an output struct
     // ...

     return lmdrouter.CustomRes(http.StatusOK, nil, output)
}

type Middleware

type Middleware func(Handler) Handler

Middleware is a function that receives a handler function (the next function in the chain, possibly another middleware or the actual handler matched for a req), and returns a handler function. These functions are quite similar to HTTP middlewares in other libraries.

Example middleware that logs all reqs:

func loggerMiddleware(next lmdrouter.Handler) lmdrouter.Handler {
    return func(ctx context.Context, req events.APIGatewayProxyRequest) (
        res events.APIGatewayProxyResponse,
        err error,
    ) {
        format := "[%s] [%s %s] [%d]%s"
        level := "INF"
        var code int
        var extra string

        res, err = next(ctx, req)
        if err != nil {
            level = "ERR"
            code = http.StatusInternalServerError
            extra = " " + err.ErrorRes()
        } else {
            code = res.StatusCode
            if code >= 400 {
                level = "ERR"
            }
        }

        log.Printf(format, level, req.HTTPMethod, req.Path, code, extra)

        return res, err
    }
}

type Router

type Router struct {
	// contains filtered or unexported fields
}

Router is the main type of the library. Lambda routes are registered to it, and it's Handler method is used by the lambda to match reqs and execute the appropriate handler.

func NewRouter

func NewRouter(basePath string, middleware ...Middleware) (l *Router)

NewRouter creates a new Router object with a base path and a list of zero or more global middleware functions. The base path is necessary if the lambda function is not going to be mounted to a domain's root (for example, if the function is mounted to "https://my.app/api", then the base path must be "/api"). Use an empty string if the function is mounted to the root of the domain.

func (*Router) Handler

func (l *Router) Handler(
	ctx context.Context,
	req events.APIGatewayProxyRequest,
) (events.APIGatewayProxyResponse, error)

Handler receives a context and an API Gateway Proxy req, and handles the req, matching the appropriate handler and executing it. This is the method that must be provided to the lambda's `main` function:

package main

import (
    "github.com/aws/aws-lambda-go/lambda"
    "github.com/aquasecurity/lmdrouter"
)

var router *lmdrouter.Router

func init() {
    router = lmdrouter.NewRouter("/api", loggerMiddleware, authMiddleware)
    router.Route(http.MethodGet, "/", listSomethings)
    router.Route(http.MethodPost, "/", postSomething, someOtherMiddleware)
    router.Route(http.MethodGet, "/:id", getSomething)
    router.Route("PUT", "/:id", updateSomething)
    router.Route(http.MethodDelete, "/:id", deleteSomething)
}

func main() {
    lambda.Start(router.Handler)
}

func (*Router) Route

func (l *Router) Route(method, path string, handler Handler, middleware ...Middleware)

Route registers a new route, with the provided HTTP method name and path, and zero or more local middleware functions.

func (*Router) ServeHTTP

func (l *Router) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServerHTTP implements the net/http.Handler interface in order to allow lmdrouter applications to be used outside of AWS Lambda environments, most likely for local development purposes