-   [](https://platform.exaloop.io/)
-   Cloud
-   AWS Lambda

# AWS Lambda

Compile a Codon handler into a native executable that receives events through the AWS Lambda Runtime API. The deployed application needs its native libraries, but not the compiler or the CLI's Python environment. Explicit Python interoperability still requires the application's Python environment.

## Create a Handler

Register the matching Lambda SDK if it is not included in your distribution:

```sh title="Terminal"
exaloop plugin add aws-lambda --path /path/to/sdk/aws-lambda
exaloop init risk-handler --kind aws-lambda --name risk
```

The generated target uses `kind = "aws-lambda"`. Its source explicitly starts the runtime with a handler; no dynamic module loading or `_HANDLER` lookup is required. For example:

```python title="Source"
import exaloop.aws_lambda as aws_lambda


def handler(event, context):
    balance = event["balance"].as_float()
    probability = event["probability"].as_float()
    if balance < 0 or not 0 <= probability <= 1:
        raise ValueError("invalid loan inputs")
    return {"expected_loss": balance * probability}


aws_lambda.run(handler)
```

The event is a native `json.JSON` value. The return value must be JSON-serializable. An exception becomes a Lambda invocation error; the runtime remains available for later events. Transport failures terminate the runtime instead of rerunning the handler or treating an unacknowledged response as successful.

## Context and Initialization

`Context` exposes `aws_request_id`, `invoked_function_arn`, `deadline_ms`, `invocation_id`, `function_name`, `function_version`, and `memory_limit_in_mb`. `get_remaining_time_in_millis()` returns the nonnegative remaining time. Use it to bound application I/O and finish before the invocation deadline.

Use `aws_lambda.run(handler, initialize=setup)` for a no-argument setup function called once before polling. Setup exceptions are reported as initialization errors and terminate the process. Exceptions raised before `run` cannot be reported through this hook. Reuse clients across warm invocations, but reconnect after stale connections and keep request-specific data out of global state.

The runtime emits JSON lifecycle logs with request IDs to stderr and propagates the current AWS trace header. Application stdout/stderr is available to CloudWatch. Trace-header propagation is not automatic instrumentation of service calls, and AWS X-Ray is separate from the compiler's XRay profiler.

## Invoke Locally

Place this event in your project's `event.json`:

```json title="JSON"
{"balance": 250000.0, "probability": 0.02}
```

From the project directory:

```sh title="Terminal"
exaloop --target risk doctor
exaloop --target risk run event.json
exaloop --target risk run event.json event.json --timeout 10
```

`run` compiles the executable and invokes it through a loopback Runtime API server. Multiple event files use one warm process. Responses are JSON lines on stdout; application logs go to stderr. Any handler error produces a nonzero CLI exit status. `--timeout` bounds initialization and each invocation; it does not include compilation. The local context reports memory size zero because the harness does not impose Lambda's memory limit.

This harness is not AWS's Runtime Interface Emulator. Validate the generated image with the AWS emulator and then in an AWS staging account before deployment. Neither local mechanism establishes IAM permissions or event-source behavior.

## Package for Lambda

Run packaging inside a matching **Ubuntu 24.04 Linux build environment**, using the Linux distribution for the intended architecture:

```sh title="Terminal"
exaloop --target risk package --output packages/risk-v1
```

The package contains the executable, bundled native dependencies, manifest, licenses, Dockerfile, and SAM template. Runtime bundling is automatic. Build defaults disable host-specific CPU tuning. Application data and dynamic libraries are not discovered automatically; use `--runtime-library` for additional native libraries and explicitly add application data to the image.

For an ARM64 package, build a single-architecture image:

```sh title="Terminal"
docker buildx build --platform linux/arm64 --provenance=false --load \
  -t risk-lambda:v1 packages/risk-v1
```

Use `linux/amd64` for an x86-64 package. Selecting a Docker platform does not cross-compile an executable that was built on another platform. Pin the Dockerfile's `BASE_IMAGE` build argument to an approved Ubuntu 24.04 image digest for repeatable production builds; rebuild to incorporate security updates.

Current Exaloop Linux distributions require glibc 2.39. The generated image uses Ubuntu 24.04; it must not be replaced with `provided:al2023`, whose glibc is older. ZIP deployment on `provided.al2023` is not supported by this integration.

The container installs CA certificates and exposes `SSL_CERT_FILE` and `SSL_CERT_DIR`. Verify TLS configuration for each SDK; an explicitly configured S3 filesystem can use `tls_ca_file_path=os.environ["SSL_CERT_FILE"]`. The root filesystem must be usable read-only; write temporary data under `/tmp`.

## Deploy and Validate

Push the image to ECR in the function's region. Deploy the generated SAM template with its `ImageUri` parameter set to the immutable ECR image digest. The template creates a function and a logging-only execution role. It does not create public URLs, S3 permissions, queues, or event-source mappings. Packaging itself does not contact AWS or create resources.

Configure service permissions on the execution role, not as embedded access keys. For S3, use the native Data SDK's default credential provider chain and narrowly scoped bucket permissions. Test real role credentials, TLS, network access, timeouts, and warm-client reuse in staging.

For S3-triggered batch processing, S3 to SQS to Lambda provides buffering and controlled retries. Your handler must implement idempotent outputs, the configured SQS partial-batch response contract, and dead-letter behavior. Do not assume exactly-once delivery. The runtime receives raw JSON events; trigger-specific adapters and permissions are not generated.

Retain image digests and publish function versions for alias-based rollback. Measure cold initialization, warm latency, memory, and cost using representative data before making performance claims.

## Supported Scope

This integration handles buffered JSON requests, one invocation at a time in ordinary Lambda execution environments. Managed Instances concurrency, response streaming, SnapStart hooks, and in-Lambda compiler profiling are not supported. Profile or optimize the handler's computation in a separate native target.

Source: https://platform.exaloop.io/cloud/aws-lambda/