{"id":19561373,"url":"https://github.com/m-mizutani/golambda","last_synced_at":"2025-04-27T00:31:11.732Z","repository":{"id":39925747,"uuid":"319832154","full_name":"m-mizutani/golambda","owner":"m-mizutani","description":"A suite of Go utilities for AWS Lambda functions to ease adopting best practices.","archived":false,"fork":false,"pushed_at":"2023-02-25T10:52:05.000Z","size":522,"stargazers_count":22,"open_issues_count":5,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-26T07:08:33.050Z","etag":null,"topics":["aws-lambda","go","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/m-mizutani.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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-12-09T03:35:40.000Z","updated_at":"2024-02-26T10:47:56.000Z","dependencies_parsed_at":"2024-06-19T01:39:35.297Z","dependency_job_id":"3aa25b9f-ed0f-4c23-aa06-154ad19dac17","html_url":"https://github.com/m-mizutani/golambda","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m-mizutani%2Fgolambda","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m-mizutani%2Fgolambda/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m-mizutani%2Fgolambda/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m-mizutani%2Fgolambda/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/m-mizutani","download_url":"https://codeload.github.com/m-mizutani/golambda/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251072279,"owners_count":21532004,"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-lambda","go","golang"],"created_at":"2024-11-11T05:11:13.777Z","updated_at":"2025-04-27T00:31:11.450Z","avatar_url":"https://github.com/m-mizutani.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# golambda [![test](https://github.com/m-mizutani/golambda/actions/workflows/test.yml/badge.svg)](https://github.com/m-mizutani/golambda/actions/workflows/test.yml) [![gosec](https://github.com/m-mizutani/golambda/actions/workflows/gosec.yml/badge.svg)](https://github.com/m-mizutani/golambda/actions/workflows/gosec.yml) [![trivy](https://github.com/m-mizutani/golambda/actions/workflows/trivy.yml/badge.svg)](https://github.com/m-mizutani/golambda/actions/workflows/trivy.yml) [![Report card](https://goreportcard.com/badge/github.com/m-mizutani/golambda)](https://goreportcard.com/report/github.com/m-mizutani/golambda) [![Go Reference](https://pkg.go.dev/badge/github.com/m-mizutani/golambda.svg)](https://pkg.go.dev/github.com/m-mizutani/golambda)\n\n\nA suite of Go utilities for AWS Lambda functions to ease adopting best practices.\n\n## Overview\n### Features\n\n- **[Event decapsulation](#source-event-decapsulation)**: Parse event data received when invoking. Also `golambda` make easy to write unit test of Lambda function\n- **[Structured logging](#structured-logging)**: `golambda` provides requisite minimum logging interface for Lambda function. It output log as structured JSON.\n- **[Error handling](#error-handling)**: Error structure with arbitrary variables and stack trace feature.\n- **[Get secret parameters](#get-secret-parameters)**: Secret values should be stored in AWS Secrets Manager and can be got easily.\n\nNOTE: The suite is **NOT** focusing to Lambda function for API gateway, but partially can be leveraged for the function.\n\n### How to use\n\n```\n$ go get github.com/m-mizutani/golambda/v2\n```\n\n\n## Source event decapsulation\n\nLambda function can have event source(s) such as SQS, SNS, etc. The main data is encapsulated in their data structure. `golambda` provides not only decapsulation feature for Lambda execution but also encapsulation feature for testing. Following event sources are supported for now.\n\n- SQS body: `DecapSQS`\n- SNS message: `DecapSNS`\n- SNS message over SQS: `DecapSNSoverSQS`\n\n### Lambda implementation\n\n```go\npackage main\n\nimport (\n\t\"strings\"\n\n\t\"github.com/m-mizutani/golambda/v2\"\n)\n\n// MyEvent is exported for test\ntype MyEvent struct {\n\tMessage string `json:\"message\"`\n}\n\n// Handler is exported for test\nfunc Handler(ctx context.Context, event *golambda.Event) (string, error) {\n\t// Decapsulate body message(s) in SQS Event structure\n\tevents, err := event.DecapSQS()\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\n\tvar response []string\n\t// Iterate body message(S)\n\tfor _, ev := range events {\n\t\tvar msg MyEvent\n\t\t// Unmarshal golambda.Event to MyEvent\n\t\tif err := ev.Bind(\u0026msg); err != nil {\n\t\t\treturn \"\", err\n\t\t}\n\n\t\t// Do something\n\t\tresponse = append(response, msg.Message)\n\t}\n\n\treturn strings.Join(response, \":\"), nil\n}\n\nfunc main() {\n\tgolambda.Start(Handler)\n}\n```\n\n### Unit test\n\n```go\npackage main_test\n\nimport (\n\t\"testing\"\n\n\t\"github.com/m-mizutani/golambda/v2\"\n\t\"github.com/stretchr/testify/require\"\n\n\tmain \"github.com/m-mizutani/golambda/v2/example/decapEvent\"\n)\n\nfunc TestHandler(t *testing.T) {\n\tmessages := []main.MyEvent{\n\t\t{\n\t\t\tMessage: \"blue\",\n\t\t},\n\t\t{\n\t\t\tMessage: \"orange\",\n\t\t},\n\t}\n\tevent, err := golambda.NewSQSEvent(messages)\n\trequire.NoError(t, err)\n\n\tresp, err := main.Handler(event)\n\trequire.NoError(t, err)\n\trequire.Equal(t, \"blue:orange\", resp)\n}\n```\n\n## Structured logging\n\nLambda function output log data to CloudWatch Logs by default. CloudWatch Logs and Insights that is rich CloudWatch Logs viewer supports JSON format logs. Therefore JSON formatted log is better for Lambda function.\n\n`golambda` provides `Logger` for JSON format logging. It has `With()` to add a pair of key and value to a log message. `Logger` has lambda request ID by default if you use the logger with `golambda.Start()`. `Logger` is provided as [zlog.Logger](https://github.com/m-mizutani/zlog). `RenewLogger()` allows you to reconfigure logging setting.\n\n### Output with temporary variable\n\n```go\nv1 := \"say hello\"\ngolambda.Logger.With(\"var1\", v1).Info(\"Hello, hello, hello\")\n/* Output:\n{\n\t\"level\": \"info\",\n\t\"lambda.requestID\": \"565389dc-c13f-4fc0-b113-xxxxxxxxxxxx\",\n\t\"time\": \"2020-12-13T02:44:30Z\",\n\t\"var1\": \"say hello\",\n\t\"message\": \"Hello, hello, hello\"\n}\n*/\n```\n\n### Log level\n\n`golambda.Logger` (`golambda.LambdaLogger` type) provides following log level. Log level can be configured by environment variable `LOG_LEVEL`.\n\n- `TRACE`\n- `DEBUG`\n- `INFO`\n- `WARN`\n- `ERROR`\n\nLambda function should return error to top level function when occurring unrecoverable error, should not exit suddenly. Therefore `PANIC` and `FATAL` is not provided according to the thought.\n\n## Error handling\n\n**NOTE: `golambda.Error` is obsoleted and use [github.com/m-mizutani/goerr](https://github.com/m-mizutani/goerr) instead.**\n\n`golambda.Error` can have pairs of key and value to keep context of error. For example, `golambda.Error` can bring original string data when failed to unmarshal JSON. The string data can be extracted in caller function.\n\nAlso, `golambda.Start` supports general error handling:\n\n1. Output error log with\n    - Pairs of key and value in `goerr.Error` of [goerr](https://github.com/m-mizutani/goerr) as `error.values`\n    - Stack trace of error as `error.stacktrace`\n2. Send error record to sentry.io if `SENTRY_DSN` is set as environment variable\n    - Stack trace of `golambda.Error` is also available in sentry.io by compatibility with `github.com/pkg/errors`\n    - Output event ID of sentry to log as `error.sentryEventID`\n\t- You can set `SENTRY_ENV` and `SENTRY_RELEASE` also optionally.\n\n```go\npackage main\n\nimport (\n\t\"github.com/m-mizutani/golambda/v2\"\n)\n\n// Handler is exported for test\nfunc Handler(event golambda.Event) (interface{}, error) {\n\ttrigger := \"something wrong\"\n\treturn nil, goerr.New(\"oops\").With(\"trigger\", trigger)\n}\n\nfunc main() {\n\tgolambda.Start(Handler)\n}\n```\n\nThen, `golambda` output following log to CloudWatch.\n\n```json\n{\n    \"level\": \"error\",\n    \"lambda.requestID\": \"565389dc-c13f-4fc0-b113-f903909dbd45\",\n    \"trigger\": \"something wrong\",\n    \"stacktrace\": [\n        {\n            \"func\": \"main.Handler\",\n            \"file\": \"xxx/your/project/src/main.go\",\n            \"line\": 27\n        },\n        {\n            \"func\": \"github.com/m-mizutani/golambda.Start.func1\",\n            \"file\": \"xxx/github.com/m-mizutani/golambda/lambda.go\",\n            \"line\": 107\n        }\n    ],\n    \"time\": \"2020-12-13T02:42:48Z\",\n    \"message\": \"oops\"\n}\n```\n\n## Get secret parameters\n\nIn general, parameters of Lambda function are stored sa environment variable, such as `LOG_LEVEL`. However secret parameters such as credential, API key/token, etc should be stored in AWS Secrets Manager or Parameter Store to control access permission more explicitly in many cases.\n\n`golambda.GetSecretValues` fetches values of AWS Secrets Manager and binds to a structure variable.\n\n```go\ntype mySecret struct {\n    Token string `json:\"token\"`\n}\nvar secret mySecret\nif err := golambda.GetSecretValues(os.Getenv(\"SECRET_ARN\"), \u0026secret); err != nil {\n    log.Fatal(\"Failed: \", err)\n}\n\n// Access to other service with secret.Token\n```\n\n## License\n\nSee [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm-mizutani%2Fgolambda","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fm-mizutani%2Fgolambda","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm-mizutani%2Fgolambda/lists"}