A lightweight AWS Lambda Custom Runtime for Elixir
## Why Mayfly?
- **A behaviour, not a string** – `use Mayfly.Handler`, implement `handle/3`, optionally `init/1` for cold-start work. Compile-time checked.
- **`mix release` is the build** – add the `Mayfly.Release` steps to your release and get `lambda.zip`. No special `MIX_ENV`, umbrellas and multiple releases work.
- **No Docker needed** – with the Mayfly ERTS layer your zip contains only BEAM files and builds on any OS in seconds.
- **Honest error reporting** – exceptions, exits, bad return values, unencodable results and misconfigured handlers all reach Lambda as proper errors with Elixir stack traces.
- **Current Lambda features** – response streaming (incl. Function URL preludes), tenant isolation, invocation ids, Managed Instances concurrency, JSON structured logging, X-Ray trace propagation.
- **Zero runtime dependencies** – built-in `JSON`, own HTTP client over `:gen_tcp`; `:telemetry` optional.
- **Nothing starts implicitly** – Mayfly has no application callback; `mix test` and `iex` in your project are untouched.
## Quick start
```bash
mix lambda.new hello --iac sam # new project + SAM (or terraform | cdk); needs mayfly in deps or a checkout
```
Or by hand:
```elixir
# mix.exs
def project do
[
app: :my_app,
releases: [
lambda: [
steps: [&Mayfly.Release.prepare/1, :assemble, &Mayfly.Release.bootstrap/1, &Mayfly.Release.zip/1],
mayfly: [handler: MyApp.Handler, layer: true]
]
],
deps: [{:mayfly, "~> 1.0.0-rc"}]
]
end
```
```elixir
# lib/my_app/handler.ex
defmodule MyApp.Handler do
use Mayfly.Handler
@impl true
def handle(event, %Mayfly.Context{} = ctx, _state) do
{:ok, %{message: "Hello from Elixir!", request_id: ctx.request_id, event: event}}
end
end
```
```bash
mix lambda.invoke MyApp.Handler '{"name":"world"}' # run it locally
MIX_ENV=prod mix release lambda # -> _build/prod/rel/lambda/lambda.zip
aws lambda create-function --function-name hello \
--runtime provided.al2023 --architectures arm64 \
--handler MyApp.Handler --zip-file fileb://_build/prod/rel/lambda/lambda.zip \
--layers arn:aws:lambda:eu-central-1:ACCOUNT:layer:mayfly-erlang-27-3-4-arm64:1 \
--role arn:aws:iam::ACCOUNT:role/lambda-role
```
## Table of contents
- [Requirements](#requirements)
- [Writing a handler](#writing-a-handler)
- [Responses](#responses)
- [Errors](#errors)
- [Building](#building)
- [Local development](#local-development)
- [Observability](#observability)
- [Lambda Managed Instances](#lambda-managed-instances)
- [Documentation](#documentation)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
## Requirements
| | Supported |
|---|---|
| Elixir | 1.18 or newer |
| Erlang/OTP | 27, 28 or 29; public layers for the latest patch of each (OTP 29 needs Elixir ≥ 1.20), every major verified on arm64 and x86_64 |
| Lambda | `provided.al2023`, x86_64 or arm64; Lambda (default) and Managed Instances |
Upgrading from 0.x? See [guides/migrating-from-0.x.md](guides/migrating-from-0.x.md).
## Writing a handler
```elixir
defmodule MyApp.Handler do
use Mayfly.Handler
# Optional. Runs once per execution environment before the first event.
@impl true
def init(_opts) do
{:ok, %{table: System.fetch_env!("TABLE_NAME")}}
end
@impl true
def handle(event, %Mayfly.Context{} = ctx, state) do
case MyApp.Items.fetch(state.table, event["id"]) do
{:ok, item} -> {:ok, item}
:not_found -> {:error, %{errorType: "NotFound", errorMessage: "no item #{event["id"]}"}}
end
end
end
```
Set the Lambda **Handler** to `MyApp.Handler`. `event` is the decoded JSON payload (string keys). `Mayfly.Context` gives you `request_id`, `invocation_id`, `deadline_ms` (`Mayfly.Context.remaining_time_ms/1`), `function_arn`, `trace_id`, `tenant_id` and the static function config in `env`.
Legacy `Module.function` handlers (arity 1 or 2) still work; see the migration guide.
### Event sources
`Mayfly.Events` decodes the envelopes AWS services send: API Gateway / Function URL requests (`body` already a map), SQS, SNS, S3 (URL-decoded keys), EventBridge, Kinesis and DynamoDB Streams (attribute values as plain terms), with partial-batch helpers:
```elixir
case Mayfly.Events.decode(event) do
{:ok, %Mayfly.Events.HTTP.Request{method: "POST", body: body} = req} -> Mayfly.Events.HTTP.json(201, create(body), req)
{:ok, %Mayfly.Events.SQS{} = sqs} -> {:ok, Mayfly.Events.SQS.process_batch(sqs, &process/1)}
:unknown -> {:ok, event}
end
```
See [guides/events.md](guides/events.md). `mix lambda.invoke … --event sqs` (or `s3`, `eventbridge`, `dynamodb`, …) wraps a payload in a realistic envelope for local testing.
## Responses
`{:ok, value}` with any JSON-encodable value is sent as `application/json`. For anything else use `Mayfly.Response`:
```elixir
# binary body
{:ok, %Mayfly.Response{body: png, content_type: "image/png"}}
# API Gateway / Function URL (buffered) – just return the proxy map
{:ok, %{statusCode: 200, headers: %{"content-type" => "text/html"}, body: html}}
# streaming (Function URL with RESPONSE_STREAM or InvokeWithResponseStream)
{:ok,
%Mayfly.Response{body: Stream.map(tokens, &sse/1), content_type: "text/event-stream"}
|> Mayfly.Response.stream()
|> Mayfly.Response.http(status: 200, headers: %{"cache-control" => "no-cache"})}
```
See [guides/streaming.md](guides/streaming.md).
**Plug and Phoenix.** With the companion package [`mayfly_plug`](https://github.com/bmalum/mayfly_plug) a router or endpoint *is* the handler: `use Mayfly.Plug.Handler, plug: {MyAppWeb.Endpoint, []}`. API Gateway, Function URL and ALB events become `%Plug.Conn{}`s; `send_chunked` streams with `streaming: true`. Phoenix 1.8 JSON APIs cold-start in ~0.6–0.75 s. LiveView needs a WebSocket and is out of scope. See [guides/phoenix.md](guides/phoenix.md).
## Errors
| Situation | `errorType` | Header (`Lambda-Runtime-Function-Error-Type`) |
|---|---|---|
| Exception raised | module name, e.g. `KeyError` | `Function.KeyError` |
| `{:error, "text"}` / `{:error, term}` | `HandlerError` | `Function.HandlerError` |
| `{:error, %{errorType: t, errorMessage: m}}` | `t` | `Function.