eventhandler

func ALB ¶

func ALB(h http.Handler, opts ...ALBOption) func(context.Context, events.ALBTargetGroupRequest) (events.ALBTargetGroupResponse, error)

ALB adapts h to an Application Load Balancer target group: Python's ALBResolver.

When the target group has multi-value headers on, the request carries every value of each header and query parameter, and so does the response; otherwise the response keeps the last value of each header and the last cookie, with a warning, as Python does. Query strings arrive percent-encoded from ALB and stay so in the URL, so the values read from it are decoded: Python's decode_query_parameters is always on.

func ALBEvent ¶

func ALBEvent(ctx context.Context) (events.ALBTargetGroupRequest, bool)

ALBEvent returns the Application Load Balancer event the request was built from.

func APIGatewayHTTP ¶

func APIGatewayHTTP(h http.Handler) func(context.Context, events.APIGatewayV2HTTPRequest) (events.APIGatewayV2HTTPResponse, error)

APIGatewayHTTP adapts h to an API Gateway HTTP API with payload format 2.0: Python's APIGatewayHttpResolver.

The path is the raw path without the stage prefix (unless the stage is $default), the query is the raw query string, so repeated parameters stay separate, and the cookies list becomes the Cookie header. The response joins header values with ", " and moves Set-Cookie headers to cookies.

func APIGatewayHTTPEvent ¶

func APIGatewayHTTPEvent(ctx context.Context) (events.APIGatewayV2HTTPRequest, bool)

APIGatewayHTTPEvent returns the API Gateway HTTP API (payload 2.0) event the request was built from.

func APIGatewayREST ¶

func APIGatewayREST(h http.Handler) func(context.Context, events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error)

APIGatewayREST adapts h to an API Gateway REST API proxy integration (and to an HTTP API with payload format 1.0): Python's APIGatewayRestResolver.

The request carries the event's method, path, query string (every value of the multi-value map), headers, cookies, body (base64-decoded) and the caller's source IP as RemoteAddr; routes ignore trailing slashes, as in Python. The response puts every header, Set-Cookie included, in multiValueHeaders, and base64-encodes bodies that are not text, which needs binary media types configured on the API.

func APIGatewayRESTEvent ¶

func APIGatewayRESTEvent(ctx context.Context) (events.APIGatewayProxyRequest, bool)

APIGatewayRESTEvent returns the API Gateway REST API (or HTTP API payload 1.0) event the request was built from: Python's current_event.

func BasePath ¶

func BasePath(ctx context.Context) string

BasePath returns the path prefix under which the client called the API: "/{stage}" for an API Gateway stage URL ("" for the $default stage, a custom domain or SAM local), "" for the other sources. The Swagger UI uses it for the server of its "Try it out" requests.

func Delete ¶

func Delete[In, Out any](r *Router, path string, op func(ctx context.Context, in In) (Out, error), opts ...RouteOption)

Delete registers a typed DELETE operation for path; see Register.

func Error ¶

func Error(w http.ResponseWriter, r *http.Request, err error)

Error answers the request with err, as raising it does in Python: through the error handlers of the router serving r (see OnError), else with the built-in response of a *ServiceError, a *RequestValidationError, a *ResponseValidationError or an *UnsupportedContentTypeError. Any other error is unhandled: the Lambda invocation fails with it (in debug mode, the response is a 500 with the error and the stack), and a local server answers 500. The status and the body the handler had written are discarded; the headers the middlewares set stay.

Middlewares and plain handlers call Error to fail a request the way a typed operation does by returning an error.

func FunctionURL ¶

func FunctionURL(h http.Handler) func(context.Context, events.LambdaFunctionURLRequest) (events.LambdaFunctionURLResponse, error)

FunctionURL adapts h to a Lambda Function URL in BUFFERED invoke mode: Python's LambdaFunctionUrlResolver. Requests and responses are those of APIGatewayHTTP. For RESPONSE_STREAM mode, serve the router with aws-lambda-go's lambdaurl.Start instead, which streams what it writes.

func FunctionURLEvent ¶

func FunctionURLEvent(ctx context.Context) (events.LambdaFunctionURLRequest, bool)

FunctionURLEvent returns the Lambda Function URL event the request was built from.

func Get ¶

func Get[In, Out any](r *Router, path string, op func(ctx context.Context, in In) (Out, error), opts ...RouteOption)

Get registers a typed GET operation for path; see Register.

package main

import (
	"context"
	"fmt"

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

	"github.com/alessandrolattao/powertools-lambda-go/eventhandler"
)

type Todo struct {
	ID    int    `json:"id"`
	Title string `json:"title" required:"true" minLength:"1"`
}

type GetTodo struct {
	ID     int    `path:"id" minimum:"1"`
	Fields string `query:"fields" enum:"all,title" default:"all"`
}

func main() {
	app := eventhandler.New()
	eventhandler.Get(app, "/todos/{id}", func(_ context.Context, in GetTodo) (Todo, error) {
		if in.ID == 42 {
			return Todo{}, eventhandler.NotFound("todo 42 not found")
		}
		return Todo{ID: in.ID, Title: "Buy milk"}, nil
	})

	handler := eventhandler.APIGatewayHTTP(app)
	for _, path := range []string{"/todos/1", "/todos/0", "/todos/42"} {
		resp, err := handler(context.Background(), events.APIGatewayV2HTTPRequest{
			RawPath:        path,
			RequestContext: events.APIGatewayV2HTTPRequestContext{HTTP: events.APIGatewayV2HTTPRequestContextHTTPDescription{Method: "GET"}},
		})
		if err != nil {
			panic(err)
		}
		fmt.Println(resp.StatusCode, resp.Body)
	}
}

Output:
200 {"id":1,"title":"Buy milk"}
422 {"statusCode":422,"detail":[{"loc":["path","id"],"type":"greater_than_equal"}]}
404 {"statusCode":404,"message":"todo 42 not found"}

func Head ¶

func Head[In, Out any](r *Router, path string, op func(ctx context.Context, in In) (Out, error), opts ...RouteOption)

Head registers a typed HEAD operation for path; see Register.

func MergeOpenAPI ¶

func MergeOpenAPI(cfg OpenAPIConfig, onConflict ConflictStrategy, docs ...[]byte) ([]byte, error)

MergeOpenAPI merges the OpenAPI documents of several functions into one, for an API whose routes live in separate Lambda functions: Python's OpenAPIMerge. cfg gives the document-level fields; the paths, components and tags come from docs (each an OpenAPI JSON document, such as Router.OpenAPIJSON writes). Components of the same name are replaced by the later document's, as in Python; tags of cfg come first.

Python discovers the handlers by scanning source files; a Go function's routes live in its binary, so each function writes its document at build time (or exports a function that registers its routes, for a program that imports them all) and the documents are merged here.

package main

import (
	"fmt"
	"net/http"
	"strings"

	"github.com/alessandrolattao/powertools-lambda-go/eventhandler"
)

func main() {
	orders := eventhandler.New()
	orders.HandleFunc("GET /orders", func(http.ResponseWriter, *http.Request) {})
	users := eventhandler.New()
	users.HandleFunc("GET /users", func(http.ResponseWriter, *http.Request) {})

	ordersDoc, err := orders.OpenAPIJSON()
	if err != nil {
		panic(err)
	}
	usersDoc, err := users.OpenAPIJSON()
	if err != nil {
		panic(err)
	}
	merged, err := eventhandler.MergeOpenAPI(eventhandler.OpenAPIConfig{Title: "Shop"}, eventhandler.ConflictError, ordersDoc, usersDoc)
	if err != nil {
		panic(err)
	}
	fmt.Println(strings.Contains(string(merged), `"/orders"`), strings.Contains(string(merged), `"/users"`))
}

Output:
true true

func OnError ¶

func OnError[E error](r *Router, fn func(w http.ResponseWriter, r *http.Request, err E) error)

OnError registers fn as the handler of the errors of type E: Python's exception_handler. When a typed operation, a middleware or a handler (through Error) fails with an error, the router looks for a handler:

1. a 404 *ServiceError goes to the HandleNotFound handler, if any;
2. walking the error tree from the outermost error (Unwrap, depth first), the first error whose concrete type has a handler wins;
3. otherwise the handlers of interface types, in registration order, the first one errors.As matches; a handler for error itself, Python's handler for Exception, comes last.

fn writes the response. If it returns an error instead, that error gets the built-in response (a *ServiceError, a validation error) or fails the invocation. Registering a type again replaces its handler.

package main

import (
	"context"
	"errors"
	"fmt"
	"net/http"

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

	"github.com/alessandrolattao/powertools-lambda-go/eventhandler"
)

var errOutOfStock = errors.New("out of stock")

func main() {
	app := eventhandler.New()
	eventhandler.OnError(app, func(w http.ResponseWriter, r *http.Request, err error) error {
		if errors.Is(err, errOutOfStock) {
			return eventhandler.WriteJSON(w, r, http.StatusConflict, map[string]string{"error": err.Error()})
		}
		return err // the built-in response, or a failed invocation
	})
	eventhandler.Post(app, "/orders", func(context.Context, struct{}) (string, error) {
		return "", fmt.Errorf("order 1: %w", errOutOfStock)
	})

	resp, err := eventhandler.ALB(app)(context.Background(), events.ALBTargetGroupRequest{HTTPMethod: "POST", Path: "/orders"})
	if err != nil {
		panic(err)
	}
	fmt.Println(resp.StatusCode, resp.Body)
}

Output:
409 {"error":"order 1: out of stock"}

func Patch ¶

func Patch[In, Out any](r *Router, path string, op func(ctx context.Context, in In) (Out, error), opts ...RouteOption)

Patch registers a typed PATCH operation for path; see Register.

func Post ¶

func Post[In, Out any](r *Router, path string, op func(ctx context.Context, in In) (Out, error), opts ...RouteOption)

Post registers a typed POST operation for path; see Register.

package main

import (
	"context"
	"fmt"
	"net/http"

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

	"github.com/alessandrolattao/powertools-lambda-go/eventhandler"
)

type Todo struct {
	ID    int    `json:"id"`
	Title string `json:"title" required:"true" minLength:"1"`
}

type CreateTodo struct {
	Body Todo
}

func main() {
	app := eventhandler.New()
	eventhandler.Post(app, "/todos", func(_ context.Context, in CreateTodo) (eventhandler.Response[Todo], error) {
		in.Body.ID = 7
		return eventhandler.Response[Todo]{
			StatusCode: http.StatusCreated,
			Header:     http.Header{"Location": {"/todos/7"}},
			Body:       in.Body,
		}, nil
	}, eventhandler.StatusCode(http.StatusCreated))

	resp, err := eventhandler.APIGatewayREST(app)(context.Background(), events.APIGatewayProxyRequest{
		HTTPMethod: "POST", Path: "/todos", Body: `{"title":"Write docs"}`,
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(resp.StatusCode, resp.MultiValueHeaders["Location"], resp.Body)
}

Output:
201 [/todos/7] {"id":7,"title":"Write docs"}

func Put ¶

func Put[In, Out any](r *Router, path string, op func(ctx context.Context, in In) (Out, error), opts ...RouteOption)

Put registers a typed PUT operation for path; see Register.

func Register ¶

func Register[In, Out any](r *Router, pattern string, op func(ctx context.Context, in In) (Out, error), opts ...RouteOption)

Register registers a typed operation for pattern, which must name a method ("GET /todos/{id}"): the handler receives its input bound from the request into In and returns the Out written as the response, the Go side of Python's routes with data validation.

In is a struct whose fields say where their values come from:

type GetTodo struct {
	ID      int    `path:"id" minimum:"1"`
	Fields  string `query:"fields" enum:"all,title"`
	TraceID string `header:"X-Trace-Id"`
	Session string `cookie:"session"`
}

A field named Body is the request body, decoded from JSON (a []byte Body takes the raw body of any content type). Fields tagged formData:"name" are form fields of an application/x-www-form-urlencoded or multipart/form-data body; a *multipart.FileHeader (or a slice of them) is an uploaded file. Embedded structs contribute their fields. Fields without one of these tags or names are left alone.

Values are converted to the field's type: strings, booleans, integers, floats, types implementing encoding.TextUnmarshaler (time.Time), pointers to them (nil when absent) and slices of them (every value of a repeated parameter; header values split on commas). Constraints use the tags of github.com/swaggest/jsonschema-go: required, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, minLength, maxLength, pattern, enum, format, minItems, maxItems, default, description, example, deprecated. Path parameters are always required.

The same schemas validate the request, describe the operation in the OpenAPI document and, when enabled, validate the response, so the three cannot drift. A request that does not conform answers 422 with Python's body; a body of a content type the operation does not read answers 415.

Out is written as JSON with the route's status (200 unless StatusCode says otherwise), or as a Response when the operation picks its own status, headers and cookies. An error from op is answered through the error handlers (see OnError); an error none handles fails the invocation, as an exception does in Python.

The schemas compile here, once: Register panics when the pattern is invalid or has no method, when In is not a struct or binds a field of a type it cannot convert, when the path parameters of the pattern and of In differ, or when a schema uses a JSON Schema keyword or format the built-in validator does not enforce (see docs/eventhandler-openapi.md), which only a type's own schema methods can add.

func RegisterRegexp ¶

func RegisterRegexp[In, Out any](r *Router, method string, re *regexp.Regexp, op func(ctx context.Context, in In) (Out, error), opts ...RouteOption)

RegisterRegexp registers a typed operation for a regular expression route: see Register and Router.HandleRegexp. The named groups of re are the path parameters.

func RequestFromContext ¶

func RequestFromContext(ctx context.Context) (*http.Request, bool)

RequestFromContext returns the request a router is serving with ctx, the context of the request or one derived from it (the context a typed operation receives). It is how a typed operation reads what its input struct does not bind, as Python's Request parameter does.

func VPCLattice ¶

func VPCLattice(h http.Handler) func(context.Context, eventsource.VPCLatticeEvent) (VPCLatticeResponse, error)

VPCLattice adapts h to a VPC Lattice target group with event structure version 1: Python's VPCLatticeResolver. Repeated query parameters arrive folded with commas: list parameters of typed operations split them.

func VPCLatticeEvent ¶

func VPCLatticeEvent(ctx context.Context) (eventsource.VPCLatticeEvent, bool)

VPCLatticeEvent returns the VPC Lattice (version 1) event the request was built from.

func VPCLatticeV2 ¶

func VPCLatticeV2(h http.Handler) func(context.Context, eventsource.VPCLatticeEventV2) (VPCLatticeResponse, error)

VPCLatticeV2 adapts h to a VPC Lattice target group with event structure version 2, the one AWS recommends: Python's VPCLatticeV2Resolver. Headers and query parameters keep all their values.

func VPCLatticeV2Event ¶

func VPCLatticeV2Event(ctx context.Context) (eventsource.VPCLatticeEventV2, bool)

VPCLatticeV2Event returns the VPC Lattice version 2 event the request was built from.

func WriteJSON ¶

func WriteJSON(w http.ResponseWriter, r *http.Request, status int, v any) error

WriteJSON writes v as a JSON response with status, encoded with the serializer of the router serving r (see WithSerializer), the way the router writes its own JSON responses.