Skip to main content
Markdown

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:

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:

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
{"balance": 250000.0, "probability": 0.02}

From the project directory:

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:

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:

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.