lmdrouter

README

lmdrouter

Go HTTP router library for AWS API Gateway-invoked Lambda Functions

Table of Contents

• Overview
  • Use Case
  • Features
• Status
• Installation
• Usage
• License

Overview

lmdrouter is a simple-to-use library for writing AWS Lambda functions in Go that listen to events of type API Gateway Proxy Request. It allows creating a lambda function that can match requests based on their URI, just like an HTTP server would.

The library provides an interface not unlike the standard net/http.Mux type or community libraries such as httprouter and chi.

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 at a global and per-resource level.
• Supports path parameters with a simple ":" format (e.g. "/posts/:id").
• Provides ability to automatically "unmarshal" an API Gateway request to an arbitrary Go struct, with data coming either from path and query string parameters, or from the request body (only JSON requests are currently supported).
• Provides ability to automatically "marshal" responses of any type to an API Gateway response (only JSON responses are currently generated).

Status

This is a very early, alpha release. API is subject to change.

Installation

go get github.com/aquasecurity/lmdrouter

Usage

lmdrouter is meant to be used inside Go Lambda functions.

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("GET", "/", listSomethings)
    router.Route("POST", "/", postSomething, someOtherMiddleware)
    router.Route("GET", "/:id", getSomething)
    router.Route("PUT", "/:id", updateSomething)
    router.Route("DELETE", "/:id", deleteSomething)
}

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

// the rest of the code is a redacted example, it will probably reside in a
// separate package inside your project

type listSomethingsInput struct {
    ID                string   `lambda:"path.id"`                // a path parameter declared as :id
    ShowSomething     bool     `lambda:"query.show_something"`   // a query parameter named "show_something"
    AcceptedLanguages []string `lambda:"header.Accept-Language"` // a multi-value header parameter
}

type postSomethingInput struct {
    Title   string    `json:"title"`
    Date    time.Time `json:"date"`
}

func listSomethings(ctx context.Context, req events.APIGatewayProxyRequest) (
    res events.APIGatewayProxyResponse,
    err error,
) {
    // parse input from request and path parameters
    var input listSomethingsInput
    err = lmdrouter.UnmarshalRequest(req, false, &input)
    if err != nil {
        return lmdrouter.HandleError(err)
    }

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

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

func postSomethings(ctx context.Context, req events.APIGatewayProxyRequest) (
    res events.APIGatewayProxyResponse,
    err error,
) {
    // parse input from request body
    var input postSomethingsInput
    err = lmdrouter.UnmarshalRequest(req, true, &input)
    if err != nil {
        return lmdrouter.HandleError(err)
    }

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

    return lmdrouter.MarshalResponse(http.StatusCreated, nil, output)
}

func loggerMiddleware(next lmdrouter.Handler) lmdrouter.Handler {
    return func(ctx context.Context, req events.APIGatewayProxyRequest) (
        res events.APIGatewayProxyResponse,
        err error,
    ) {
        // [LEVEL] [METHOD PATH] [CODE] EXTRA
        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.Error()
    	} else {
    	    code = res.StatusCode
    	    if code >= 400 {
    	        level = "ERR"
    	    }
        }

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

        return res, err
    }
}

Static Compilation for AWS Lambda

To ensure Lambda applications using lmdrouter (or any Lambda applications written in Go, for that matter) will properly work in AWS's Go runtime, make sure to compile your applications statically. You can either disable CGO completely using CGO_ENABLED=0, or use the following build flags:

go build -tags netgo -ldflags "-s -w"

License

This library is distributed under the terms of the Apache License 2.0.

Documentation

Overview

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

The library allows creating functions that can match requests 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 request to an arbitrary Go struct, with data coming either from path and query string parameters, or from the request body (only JSON requests are currently supported). See the documentation for the `UnmarshalRequest` 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 MarshalResponse function for more information.

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

Index

• Variables
• func BasicAuth(req events.APIGatewayProxyRequest) (user, pass string)
• func HandleError(err error) (events.APIGatewayProxyResponse, error)
• func MarshalResponse(status int, headers map[string]string, data interface{}) (events.APIGatewayProxyResponse, error)
• func UnmarshalRequest(req events.APIGatewayProxyRequest, body bool, 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)

Variables

var ExposeServerErrors = true

ExposeServerErrors is a boolean indicating whether the HandleError 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 BasicAuth

func BasicAuth(req events.APIGatewayProxyRequest) (user, pass string)

BasicAuth attempts to parse a username and password from the request's "Authorization" header. If the Authorization header is missing, or does not contain valid Basic HTTP Authentication date, empty values will be returned.

func HandleError

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

HandleError 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 MarshalResponse

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

MarshalResponse 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 UnmarshalRequest

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

UnmarshalRequest "fills" out a target Go struct with data from the request. If body is true, then the request body is assumed to be JSON and simply unmarshaled into the target (taking into account that the request body may be base-64 encoded). After than, 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 or headers, according to the tag definition.

Field types are currently limited to string, all int types, all uint types, all float types, bool and slices of the aforementioned 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:

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"`
}

Types

type HTTPError

type HTTPError struct {
	Code    int    `json:"code"`
	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 error.

type Handler

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

Handler is a request handler function. It receives a context, and the API Gateway's proxy request 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.UnmarshalRequest(req, false, &input)
    if err != nil {
        return lmdrouter.HandleError(err)
    }

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

    return lmdrouter.MarshalResponse(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 request), and returns a handler function. These functions are quite similar to HTTP middlewares in other libraries.

Example middleware that logs all requests:

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.Error()
        } 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 requests 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 request, and handles the request, 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("GET", "/", listSomethings)
    router.Route("POST", "/", postSomething, someOtherMiddleware)
    router.Route("GET", "/:id", getSomething)
    router.Route("PUT", "/:id", updateSomething)
    router.Route("DELETE", "/: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