shim

README

Shim

Shim is a thin layer between API Gateway integration requests via Lambda and the standard library http.Handler interface. It allows you to write plain ol' Go and run it on Lambda with minimal modifications. Bring your own router!

Shim uses Go modules to model its dependencies.

Example

For an extensive example on how shim fits in with other AWS serverless tooling like SAM Local and the Serverless Application Model (SAM) specification head over to the this example in the wiki

Note: API Gateway

Make sure that proxy pass integration in API Gateway is enabled to make sure your application receives every request sent to your API Gateway endpoint.

Code

With Rest API (API Gateway Proxy Request, Response)

package main

import (
  "fmt"
  "net/http"

  "github.com/aws/aws-lambda-go/lambda"

  "github.com/iamatypeofwalrus/shim"
)

func main() {
  // Create a router as normal. Any router that satisfies the http.Handler interface
  // is accepted!
  mux := http.NewServeMux()
  mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
    fmt.Fprint(w, "hello, world")
  })

  s := shim.HandleRestApiRequests(mux)

  // Pass your router to shim and let Lambda handle the rest
  lambda.Start(s.Handle)
}

With HTTP API (API Gateway V2 Request, Response)

package main

import (
  "fmt"
  "net/http"

  "github.com/aws/aws-lambda-go/lambda"

  "github.com/iamatypeofwalrus/shim"
)

func main() {
  // Create a router as normal. Any router that satisfies the http.Handler interface
  // is accepted!
  mux := http.NewServeMux()
  mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
    fmt.Fprint(w, "hello, world")
  })

  s := shim.HandleHttpApiRequests(mux)

  // Pass your router to shim and let Lambda handle the rest
  lambda.Start(s.Handle)
}

With Debugging Logger

You can pull logs from various steps in the shim by passing the SetDebugLogger option. It accepts any logger that provides Printf functions a lá the standard library logger.

func main() {
  ...

  l := log.New(os.Stdout, "", log.LstdFlags)
  shim := shim.New(
    nil, // or your mux
    shim.SetDebugLogger(l)
  )

  ...
}

There is also a shim for the slog package

func main() {
  ...

  // Debug with Slog calls the Debug method on slog. Slog defaults to INFO, so it needs to be set to Debug so you can see the messages
  logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelDebug}))
  shim := shim.New(
    nil, // or your mux
    shim.SetDebugWithSlog(l)
  )

  ...
}

Documentation

Overview

Package shim provides a thin layer between the Lambda API Gateway integrations and the standard library `http.Handler` interface. Bring your own router.

Index

• func NewAPIGatewayProxyResponse(rw *ResponseWriter) events.APIGatewayProxyResponse
• func NewApiGatewayV2HttpResponse(rw *ResponseWriter) events.APIGatewayV2HTTPResponse
• func NewHttpRequestFromAPIGatewayProxyRequest(ctx context.Context, event events.APIGatewayProxyRequest) (*http.Request, error)
• func NewHttpRequestFromAPIGatewayV2HTTPRequest(ctx context.Context, event events.APIGatewayV2HTTPRequest) (*http.Request, error)
• func SetDebugLogger(l Log) func(*Shim)
• func SetDebugWithSlog(l slog.Logger) func(*Shim)
• type Log
• type ResponseWriter
  • func NewResponseWriter() *ResponseWriter
  • func (rw *ResponseWriter) Header() http.Header
  • func (rw *ResponseWriter) Write(b []byte) (int, error)
  • func (rw *ResponseWriter) WriteHeader(c int)
• type Shim
  • func New(h http.Handler, options ...func(*Shim)) *Shim
  • func (s *Shim) Handle(ctx context.Context, request events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error)
  • func (s *Shim) HandleHttpApiRequests(ctx context.Context, request events.APIGatewayV2HTTPRequest) (events.APIGatewayV2HTTPResponse, error)
  • func (s *Shim) HandleRestApiRequests(ctx context.Context, request events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error)

Functions

func NewAPIGatewayProxyResponse

func NewAPIGatewayProxyResponse(rw *ResponseWriter) events.APIGatewayProxyResponse

NewAPIGatewayProxyResponse converts a shim.ResponseWriter into an events.APIGatewayProxyResponse

func NewApiGatewayV2HttpResponse

func NewApiGatewayV2HttpResponse(rw *ResponseWriter) events.APIGatewayV2HTTPResponse

func NewHttpRequestFromAPIGatewayProxyRequest

func NewHttpRequestFromAPIGatewayProxyRequest(ctx context.Context, event events.APIGatewayProxyRequest) (*http.Request, error)

NewHttpRequestFromAPIGatewayProxyRequest creates an *http.Request from a context.Context and an events.APIGatewayProxyRequest

func NewHttpRequestFromAPIGatewayV2HTTPRequest

func NewHttpRequestFromAPIGatewayV2HTTPRequest(ctx context.Context, event events.APIGatewayV2HTTPRequest) (*http.Request, error)

NewHttpRequestFromAPIGatewayV2HTTPRequest creates an *http.Request from the context passed from the Lambda library, and the event itself.

func SetDebugLogger

func SetDebugLogger(l Log) func(*Shim)

SetDebugLogger is an option function to set the debug logger on a Shim. The debug logger gives insight into the event received from APIGateway and how shim transforms the request and response.

func SetDebugWithSlog

func SetDebugWithSlog(l slog.Logger) func(*Shim)

Types

type Log

type Log interface {
	Printf(format string, v ...interface{})
}

Log is a simple logging interface that is satisfied by the standard library logger amongst other idiomatic loggers

type ResponseWriter

type ResponseWriter struct {
	Code    int
	Headers http.Header
	Body    bytes.Buffer
}

ResponseWriter adheres to the http.ResponseWriter interface and makes the HTTP Status Code, Headers, and Body publicly accessible

func NewResponseWriter

func NewResponseWriter() *ResponseWriter

NewResponseWriter returns an ResponseWriter with the headers properly initialized

func (*ResponseWriter) Header

func (rw *ResponseWriter) Header() http.Header

Header adheres the http.ResponseWriter interface

func (*ResponseWriter) Write

func (rw *ResponseWriter) Write(b []byte) (int, error)

Write adheres to the io.Writer interface

func (*ResponseWriter) WriteHeader

func (rw *ResponseWriter) WriteHeader(c int)

WriteHeader adheres to the http.ResponseWriter interface

type Shim

type Shim struct {
	Handler http.Handler
	Log     Log
}

Shim provides a thin layer between your traditional http.Handler based application and AWS Lambda + API Gateway.

func New

func New(h http.Handler, options ...func(*Shim)) *Shim

New returns an initialized Shim with the provided http.Handler. If no http.Handler is provided New will use http.DefaultServiceMux

func (*Shim) Handle

func (s *Shim) Handle(ctx context.Context, request events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error)

Handle converts an APIGatewayProxyRequest converts an APIGatewayProxyRequest into an http.Request and passes it to the given http.Handler along with a ResponseWriter. The response from the handler is converted into an APIGatewayProxyResponse.

func (*Shim) HandleHttpApiRequests

func (s *Shim) HandleHttpApiRequests(ctx context.Context, request events.APIGatewayV2HTTPRequest) (events.APIGatewayV2HTTPResponse, error)

HandleHttpApiRequests converts an APIGatewayV2HTTPRequest into an http.Request and passes it to the http.Handler. Http responses are converted into APIGatewayV2HTTPResponse

func (*Shim) HandleRestApiRequests

func (s *Shim) HandleRestApiRequests(ctx context.Context, request events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error)

HandleRestApiRequests converts an APIGatewayProxyRequest into an http.Request and passes it to the http.Handler. Http responses are converted into APIGatewayProxyResponse.