{"id":24919820,"url":"https://github.com/webbgeorge/lambdah","last_synced_at":"2025-04-09T18:08:46.135Z","repository":{"id":100510113,"uuid":"261014282","full_name":"webbgeorge/lambdah","owner":"webbgeorge","description":"A useful abstraction layer over AWS Lambda functions written in Go.","archived":false,"fork":false,"pushed_at":"2020-07-30T01:19:59.000Z","size":92,"stargazers_count":17,"open_issues_count":18,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-23T20:04:47.685Z","etag":null,"topics":["aws","aws-golang","aws-lambda","framework","go","golang","lambda","lambda-functions","middleware"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webbgeorge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-03T20:24:06.000Z","updated_at":"2021-08-28T04:04:39.000Z","dependencies_parsed_at":"2023-07-29T22:32:14.862Z","dependency_job_id":null,"html_url":"https://github.com/webbgeorge/lambdah","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webbgeorge%2Flambdah","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webbgeorge%2Flambdah/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webbgeorge%2Flambdah/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webbgeorge%2Flambdah/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webbgeorge","download_url":"https://codeload.github.com/webbgeorge/lambdah/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248084388,"owners_count":21045125,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-golang","aws-lambda","framework","go","golang","lambda","lambda-functions","middleware"],"created_at":"2025-02-02T10:37:33.500Z","updated_at":"2025-04-09T18:08:46.114Z","avatar_url":"https://github.com/webbgeorge.png","language":"Go","readme":"# lambdah\n\n[![Godoc](https://godoc.org/github.com/webbgeorge/lambdah?status.svg)](https://pkg.go.dev/github.com/webbgeorge/lambdah)\n![CI](https://github.com/webbgeorge/lambdah/workflows/CI/badge.svg)\n[![Coverage Status](https://coveralls.io/repos/github/webbgeorge/lambdah/badge.svg?branch=master)](https://coveralls.io/github/webbgeorge/lambdah?branch=master)\n[![Go Report Card](https://goreportcard.com/badge/github.com/webbgeorge/lambdah)](https://goreportcard.com/report/github.com/webbgeorge/lambdah)\n\n**lambdah** provides a useful abstraction layer over AWS Lambda functions written in Go.\n\nFeatures:\n\n* A simple interface for writing lambda functions of all types\n* Extensible middleware framework\n* Data binding for JSON payloads\n* Highly customisable\n* Optional logging and tracing tools via middleware\n\n## Installation\n\n**lambdah** is available as a [Go module](https://github.com/golang/go/wiki/Modules) - import\nany package under `github.com/webbgeorge/lambdah` in your project to get started.\n\n## Getting started\n\n**lambdah** has handlers for many types of event. Here are two example handlers for API\nGateway Proxy Requests and SQS Messages.\n\n### API Gateway Proxy request handler\n\n```go\npackage main\n\nimport (\n\t\"net/http\"\n\n\tlambdah \"github.com/webbgeorge/lambdah/api_gateway_proxy\"\n)\n\nfunc main() {\n\tlambdah.HandlerFunc(handler).Start()\n}\n\n// handle http request via API Gateway\nfunc handler(c *lambdah.Context) error {\n\treturn c.String(http.StatusOK, \"Hello world!\")\n}\n```\n\n### SQS message handler\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\tlambdah \"github.com/webbgeorge/lambdah/sqs\"\n)\n\nfunc main() {\n\tlambdah.HandlerFunc(handler).Start()\n}\n\n// handle SQS message\nfunc handler(c *lambdah.Context) error {\n\t// Unmarshal JSON message data into a struct\n\tvar data messageData\n\terr := c.Bind(\u0026data)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\t// just log the name to CloudWatch Logs (via stdout) for the example\n\tfmt.Println(data.Name)\n\n\treturn nil\n}\n\ntype messageData struct {\n\tGreeting string `json:\"greeting\"`\n\tName     string `json:\"name\"`\n}\n```\n\n## More examples\n\nHandler type      | Example\n----------------- | -----------------\napi_gateway_proxy | [basic](examples/api_gateway_proxy/basic)\napi_gateway_proxy | [custom error handler](examples/api_gateway_proxy/custom_error_handler)\napi_gateway_proxy | [apitest](examples/api_gateway_proxy/apitest)\ncloudwatch_events | [basic](examples/cloudwatch_events/basic)\ncloudwatch_events | [middleware](examples/cloudwatch_events/middleware)\ndynamodb          | [basic](examples/dynamodb/basic)\ndynamodb          | [middleware](examples/dynamodb/middleware)\ngeneric           | [basic](examples/generic/basic)\ngeneric           | [middleware](examples/generic/middleware)\ns3                | [basic](examples/s3/basic)\ns3                | [middleware](examples/s3/middleware)\nsns               | [basic](examples/sns/basic)\nsns               | [middleware](examples/sns/middleware)\nsqs               | [basic](examples/sqs/basic)\nsqs               | [middleware](examples/sqs/middleware)\n\n## Concepts\n\n### Middleware\n\n**lambdah** provides a middleware system to allow extending the functionality of its handlers.\nUsing middleware on any handler is completely optional.\n\nEach handler includes some default middleware that you can choose to use or not. This\nincludes a `CorrelationIDMiddleware` and a `LoggerMiddleware` for all handlers. Some\nhandlers have additional default middleware, such as the\n`api_gateway_proxy.ErrorHandlerMiddleware` middleware.\n\nIn addition to default middleware, custom middleware can be created using a simple API,\ndescribed below.\n\n#### Using middleware\n\nHere is the same simple API Gateway Proxy handler from above, with the addition\nof two middleware.\n\n```go\npackage main\n\nimport (\n\t\"net/http\"\n\t\"os\"\n\n\tlambdah \"github.com/webbgeorge/lambdah/api_gateway_proxy\"\n)\n\nfunc main() {\n\tlambdah.\n\t\tHandlerFunc(handler).\n\t\tMiddleware(\n\t\t\tlambdah.CorrelationIDMiddleware(),\n\t\t\tlambdah.LoggerMiddleware(os.Stdout, nil),\n\t\t).\n\t\tStart()\n}\n\n// handle http request via API Gateway\nfunc handler(c *lambdah.Context) error {\n\treturn c.String(http.StatusOK, \"Hello world!\")\n}\n```\n\n#### Custom middleware\n\nHere is a simple example of a custom middleware for the API Gateway Proxy handler.\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\tlambdah \"github.com/webbgeorge/lambdah/api_gateway_proxy\"\n)\n\n// function which returns our custom middleware\nfunc MyCustomMiddleware() lambdah.Middleware {\n\treturn func(h lambdah.HandlerFunc) lambdah.HandlerFunc {\n\t\treturn func(c *lambdah.Context) error {\n\t\t\t// just log to CloudWatch Logs (via stdout) for the example\n\t\t\tfmt.Println(\"middleware triggered\")\n\t\t\treturn h(c)\n\t\t}\n\t}\n}\n```\n\n#### Default middleware\n\nHandler           | Default middleware\n----------------- | ------------------\napi_gateway_proxy | ErrorHandlerMiddleware, CorrelationIDMiddleware, LoggerMiddleware\ncloudwatch_events | CorrelationIDMiddleware, LoggerMiddleware\ndynamodb          | CorrelationIDMiddleware, LoggerMiddleware\ngeneric           | CorrelationIDMiddleware, LoggerMiddleware\ns3                | CorrelationIDMiddleware, LoggerMiddleware\nsns               | CorrelationIDMiddleware, LoggerMiddleware\nsqs               | CorrelationIDMiddleware, LoggerMiddleware\n\n### Binding data\n\nMany of the handler types allow you to bind payload data into a Go data structure.\n\nThis includes:\n\n* API Gateway Proxy request body (from JSON)\n* CloudWatch event detail (from JSON)\n* DynamoDB event images (from DynamoDB attribute map)\n* Generic event payload (from JSON)\n* SNS event data (from JSON)\n* SQS message data (from JSON)\n\nFor example, here is an example SNS event handler which binds JSON data:\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\tlambdah \"github.com/webbgeorge/lambdah/sns\"\n)\n\nfunc main() {\n\tlambdah.HandlerFunc(handler).Start()\n}\n\n// handle SNS event\nfunc handler(c *lambdah.Context) error {\n\t// Unmarshal JSON message data into a struct\n\tvar data messageData\n\terr := c.Bind(\u0026data)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\t// just log the name to CloudWatch Logs (via stdout) for the example\n\tfmt.Println(data.Name)\n\n\treturn nil\n}\n\ntype messageData struct {\n\tGreeting string `json:\"greeting\"`\n\tName     string `json:\"name\"`\n}\n```\n\n### Logging\n\n**lambdah** provides some built-in logging support using middleware. Logging can be \nan opinionated matter, so using this is completely optional.\n\nTo enable a logger on any type of handler, attach its `LoggerMiddleware`. This\nattaches a [zerolog](https://github.com/rs/zerolog) logger to the context of\neach event. Two arguments are required to use the logger middleware:\n \n* an `io.Writer` to write log messages to\n* a `map[string]string` of fields to add to the log data (set to nil if not wanted)\n\n```go\nlambdah.\n\tHandlerFunc(handler).\n\tMiddleware(\n\t\tlambdah.LoggerMiddleware(os.Stdout, map[string]string{\"logFieldOne\": \"valueOne\"}),\n\t).\n\tStart()\n```\n\nThe logger middleware will, by default, log the status of each processed event with\nsome basic details about the event. The logger can also be accessed within your\nhandlers and custom middleware.\n\n```go\nfunc handler(c *lambdah.Context) error {\n\tlogger := log.LoggerFromContext(c.Context)\n\tlogger.Info().Msg(\"hello logs\")\n\treturn c.String(http.StatusOK, \"Hello world!\")\n}\n```\n\n### Correlation IDs\n\n**lambdah** provides an optional `CorrelationIDMiddleware` for all of its handlers.\nThis middleware retrieves or creates a Correlation ID, which is often used for\ntracing requests through distributed systems in logs. This correlation ID is\nalways a v4 UUID e.g. `9187bcbb-052b-45e5-bffa-99f323a8aa71`.\n\nWhen used in conjunction with the `LoggerMiddleware`, each log message includes\nthe Correlation ID. Note that the `CorrelationIDMiddleware` must be included\nbefore the `LoggerMiddleware`.\n\nThe Correlation ID can also be accessed from within handlers and custom middleware:\n\n```go\nfunc handler(c *lambdah.Context) error {\n\tcid := log.CorrelationIDFromContext(c.Context)\n\t// log correlation id for example\n\tfmt.Println(cid)\n\treturn c.String(http.StatusOK, \"Hello world!\")\n}\n```\n\n#### Source of Correlation ID\n\nThe handler sources or creates the Correlation ID in different ways depending \non its type.\n\nHandler           | Correlation ID Source\n----------------- | ------------------\napi_gateway_proxy | `Correlation-Id` request header if present, otherwise is created by lambdah\ncloudwatch_events | CloudWatch Event ID\ndynamodb          | created by lambdah\ngeneric           | created by lambdah\ns3                | created by lambdah\nsns               | `correlation_id` SNS message attribute if present, otherwise is created by lambdah\nsqs               | `correlation_id` SQS message attribute if present, otherwise is created by lambdah\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebbgeorge%2Flambdah","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebbgeorge%2Flambdah","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebbgeorge%2Flambdah/lists"}