{"id":16476407,"url":"https://github.com/softprops/zig-lambda-runtime","last_synced_at":"2025-03-21T07:30:21.917Z","repository":{"id":206917564,"uuid":"717975686","full_name":"softprops/zig-lambda-runtime","owner":"softprops","description":"an aws lambda runtime for zig","archived":false,"fork":false,"pushed_at":"2024-04-21T17:00:31.000Z","size":64,"stargazers_count":25,"open_issues_count":2,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-17T12:00:06.125Z","etag":null,"topics":["aws","aws-lambda","zig","ziglang"],"latest_commit_sha":null,"homepage":"","language":"Zig","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/softprops.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2023-11-13T05:01:53.000Z","updated_at":"2025-02-16T16:31:16.000Z","dependencies_parsed_at":"2023-11-13T06:32:32.553Z","dependency_job_id":"669382b8-6770-47e4-b6a3-5ee9b8a0e5f6","html_url":"https://github.com/softprops/zig-lambda-runtime","commit_stats":null,"previous_names":["softprops/zig-lambda-runtime"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Fzig-lambda-runtime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Fzig-lambda-runtime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Fzig-lambda-runtime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Fzig-lambda-runtime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/softprops","download_url":"https://codeload.github.com/softprops/zig-lambda-runtime/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244118822,"owners_count":20400926,"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-lambda","zig","ziglang"],"created_at":"2024-10-11T12:42:24.006Z","updated_at":"2025-03-21T07:30:21.572Z","avatar_url":"https://github.com/softprops.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  zig lambda runtime\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  An implementation of the \u003ca href=\"https://docs.aws.amazon.com/lambda/latest/dg/runtimes-api.html\"\u003eaws lambda runtime\u003c/a\u003e for \u003ca href=\"https://ziglang.org/\"\u003ezig\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n  ⚡ 🦎\n\u003c/div\u003e\n\n[![Main](https://github.com/softprops/zig-lambda-runtime/actions/workflows/main.yml/badge.svg)](https://github.com/softprops/zig-lambda-runtime/actions/workflows/main.yml) ![License Info](https://img.shields.io/github/license/softprops/zig-lambda-runtime) ![Release](https://img.shields.io/github/v/release/softprops/zig-lambda-runtime) [![Zig Support](https://img.shields.io/badge/zig-0.12.0-black?logo=zig)](https://ziglang.org/documentation/0.12.0/)\n\n## 🍬 features\n\n- ⚡ small and fast\n\n  Zig is impressively fast and small by default and can be made even faster and smaller with common `optimize` compilation flags.\n  ❄ avg cold start duration `11ms` 💾 avg memory `10MB` ⚡ avg duration `1-2ms`\n\n- 📦 painless and easy packaging\n\n  Zig comes with a self-contained build tool that makes cross compilation for aws deployment targets painless `zig build -Dtarget=aarch64-linux -Doptimize={ReleaseFast,ReleaseSmall}`\n\nComing soon...\n\n- streaming response support\n\n  By default aws lambda buffers and then returns a single response to client but can be made streaming with opt in configuration\n\n- event struct types\n\n  At present it is up to lambda functions themselves to parse the and self declare event payloads structures and serialize responses. We would like to provide structs for common aws lambda event and response types to make that easier\n\n## examples\n\nBelow is an example echo lambda that echo's the event that triggered it.\n\n```zig\nconst std = @import(\"std\");\nconst lambda = @import(\"lambda\");\n\npub fn main() !void {\n    // 👇 wrap a free standing fn in a handler type\n    var wrapped = lambda.wrap(handler);\n    // 👇 start the runtime with this handler\n    try lambda.run(null, wrapped.handler());\n}\n\nfn handler(allocator: std.mem.Allocator, context: lambda.Context, event: []const u8) ![]const u8 {\n    _ = allocator;\n    _ = context;\n    return event;\n}\n```\n\n## 📼 installing\n\nCreate a new exec project with `zig init-exe`. Copy the echo handler example above into `src/main.zig`\n\nCreate a `build.zig.zon` file to declare a dependency\n\n\u003e .zon short for \"zig object notation\" files are essentially zig structs. `build.zig.zon` is zigs native package manager convention for where to declare dependencies\n\n```diff\n.{\n    .name = \"my-first-zig-lambda\",\n    .version = \"0.1.0\",\n    .dependencies = .{\n+        // 👇 declare dep properties\n+        .lambda = .{\n+            // 👇 uri to download\n+            .url = \"https://github.com/softprops/zig-lambda-runtime/archive/refs/tags/v0.2.0.tar.gz\",\n+            // 👇 hash verification\n+            .hash = \"12202c21b4111b1b549508847b0de394f2188d16560287e532441457314d7c0671fa\",\n+        },\n    },\n    .minimum_zig_version = \"0.12.0\",\n    .paths = .{\"\"},\n}\n```\n\n\u003e the hash below may vary. you can also depend any tag with `https://github.com/softprops/zig-lambda-runtime/archive/refs/tags/v{version}.tar.gz` or current main with `https://github.com/softprops/zig-lambda-runtime/archive/refs/heads/main/main.tar.gz`. to resolve a hash, omit it and let zig tell you the expected value.\n\n## 🔧 building\n\nThis library targets the provided lambda runtime, prefer `provided.al2023` the latest, which assumes an executable named `bootstrap`.\n\nTo produce one of these, add the following in your `build.zig` file\n\n```diff\nconst std = @import(\"std\");\n\npub fn build(b: *std.Build) void {\n    const target = b.standardTargetOptions(.{});\n\n    const optimize = b.standardOptimizeOption(.{});\n+   // 👇 de-reference lambda dep from build.zig.zon\n+    const lambda = b.dependency(\"lambda\", .{\n+       .target = target,\n+       .optimize = optimize,\n+   }).module(\"lambda\");\n    // 👇 create an execuable named `bootstrap`. the name `bootstrap` is important\n    var exe = b.addExecutable(.{\n        .name = \"bootstrap\",\n        .root_source_file = .{ .path = \"src/main.zig\" },\n        .target = target,\n        .optimize = optimize,\n    });\n+   // 👇 add the lambda module to executable\n+   exe.addModule(\"lambda\", lambda);\n\n    b.installArtifact(exe);\n}\n```\n\nThen build an arm linux executable by running `zig build -Dtarget=aarch64-linux --summary all`\n\n\u003e We're using `aarch64` because we'll be deploying to the `arm64` lambda runtime architecture below\n\n\u003e Also consider optimizing for faster artifact with `zig build -Dtarget=aarch64-linux -Doptimize=ReleaseFast --summary all` or smaller artifact with `zig build -Dtarget=aarch64-linux -Doptimize=ReleaseSmall --summary all`. The default is a `Debug` build which trades of speed and size for faster compilation. See `zig build --help` for more info\n\n## 📦 packaging\n\nPackage your function in zip file (aws lambda assumes a zip file) `zip -jq lambda.zip zig-out/bin/bootstrap`\n\n## 🪂 deploying\n\nThe follow shows how to deploy a lambda using a standard aws deployment tool, [aws sam cli](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html).\n\nCreate a `template.yml` sam deployment template\n\n```yaml\nAWSTemplateFormatVersion: \"2010-09-09\"\nTransform: AWS::Serverless-2016-10-31\n\nResources:\n  Function:\n    Type: AWS::Serverless::Function\n    Properties:\n      # 👇 use the latest provided runtime\n      Runtime: provided.al2023\n      # 👇 deploy on arm architecture, it's more cost effective\n      Architectures:\n        - arm64\n      MemorySize: 128\n      # 👇 the zip file containing your `bootstrap` binary\n      #    example: zip -jq lambda.zip zig-out/bin/bootstrap\n      CodeUri: \"lambda.zip\"\n      # 👇 required for zip but not used by the zig runtime, put any value you like here\n      Handler: handler\n      FunctionName: !Sub \"${AWS::StackName}\"\n      Policies:\n        - AWSLambdaBasicExecutionRole\n```\n\nCreate a `samconfig.toml` to store some local sam cli defaults\n\n\u003e this file is can be updated overtime to evolve with your infra as your infra needs evolved\n\n```toml\nversion = 1.0\n\n[default.deploy.parameters]\nresolve_s3 = true\ns3_prefix = \"zig-lambda-demo\"\nstack_name = \"zig-lambda-demo\"\nregion = \"us-east-1\"\nfail_on_empty_changeset = false\ncapabilities = \"CAPABILITY_IAM\"\n```\n\nThen run `sam deploy` to deploy it\n\n## 🥹 for budding ziglings\n\nDoes this look interesting but you're new to zig and feel left out? No problem, zig is young so most us of our new are as well. Here are some resources to help get you up to speed on zig\n\n- [the official zig website](https://ziglang.org/)\n- [zig's one-page language documentation](https://ziglang.org/documentation/0.11.0/)\n- [ziglearn](https://ziglearn.org/)\n- [ziglings exercises](https://github.com/ratfactor/ziglings)\n\n\\- softprops 2023\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftprops%2Fzig-lambda-runtime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftprops%2Fzig-lambda-runtime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftprops%2Fzig-lambda-runtime/lists"}