Dart Runtime for AWS Lambda

A 🎯 Dart Runtime for ƛ AWS Lambda

Read Introducing a Dart runtime for AWS Lambda

🚀 Experimental support for ⚡️ serverless framework

If you need to access AWS APIs in your Lambda function, please search on pub.dev for packages provided by Agilord

Features

Great performance < 10ms on event processing and < 50MB memory consumption
No need to ship the Dart runtime
Multiple event handlers
Typed events
Custom events

this package requires Dart >= 2.6 currently dart2native only supports building for the platform it is run on, so you must either build on a Linux machine or use docker

🚀 Introduction

Dart is an unsupported AWS Lambda runtime language. However, with a custom runtime you can support virtually every programming language.

There are two ways in which you could use Dart. You could bundle the Dart Runtime in a Lambda layer and use JIT compilation within the lambda execution to run a Dart program. The other is to compile a shippable binary of the Dart program.

Dart >= 2.6 introduced dart2native. The tool uses AOT (ahead-of-time) to compile a Dart program to native x64 machine code. This standalone executable is native machine code that's compiled from the specific Dart file and its dependencies, plus a small Dart runtime that handles type checking and garbage collection.

We decided to use the latter approach rather then the just-in-time compilation of Dart files. The main reason for this decision is that we wanted to avoid having to ship and maintain a standalone Dart runtime version. We would eventually have to deprecate versions, or always update the version when moving forward. Furthermore, shipping a binary has the advantage of having an always runnable version of your function in addition to performance benefits.

We want to highlight Firecracker open-source innovation from re:Invent 2019 which gives you a brief overview of Firecracker which is the underlying technology of AWS Lambda.

📦 Use

Add the following snippet to your pubspec file in pubspec.yaml.

dependencies:
  aws_lambda_dart_runtime: ^1.0.3+2

Docs are available. They are also accessible in the docs folder.

# access the docs local
pub global activate dhttpd
dhttpd --path docs

you can generate the docs with dartdoc --output docs

Build and deploy the Dart functions by the serverless framework or by custom deployment.

🧪 Serverless Framework (experimental)

Checkout serverless-dart to create your functions with serverless.

You can start your next project using the serverless-aws-dart template.

$ npx serverless install \
  --url https://github.com/katallaxie/serverless-aws-dart \
  --name hello

Every serverless workflow command should work out of the box. The template also includes an example GitHub actions configuration file which can unlock a virtuous cycle of continuous integration and deployment ( i.e all tests are run on prs and every push to master results in a deployment).

Custom deployment

The deployment is a manual task right now. We have a example/build.sh script which makes the process a bit easier. There are three steps to get your code ready to be shipped.

Compile your Dart program with dart2native main.dart -o bootstrap
Create a .zip file with zip lambda.zip bootstrap
Upload the lambda.zip to a S3 bucket or use the AWS CLI to upload it

again, you have to build this on Linux, because dart2native does not support cross-compiling

When you created your function and upload it via the the console. Please, replace arn:aws:iam::xxx:xxx with the role you created for your lambda.

aws lambda create-function --function-name dartTest \
  --handler hello.apigateway \
  --zip-file fileb://./lambda.zip \
  --runtime provided \
  --role arn:aws:iam::xxx:xxx \
  --environment Variables={DART_BACKTRACE=1} \
  --tracing-config Mode=Active

Updating a function is a fairly easy task. Rebuild your lambda.zip package and execute the following command.

aws lambda update-function-code --function-name dartTest --zip-file fileb://./lambda.zip

Events

There are a number of events that come with the Dart Runtime.

Application Load Balancer
Alexa
API Gateway
AppSync
Cloudwatch
Cognito
DynamoDB
Kinesis
S3
SQS

You can also register custom events.

import 'package:aws_lambda_dart_runtime/aws_lambda_dart_runtime.dart';

class MyCustomEvent {
  factory MyCustomEvent.fromJson(Map<String, dynamic> json) =>
      MyCustomEvent(json);

  const MyCustomEvent();
}

void main() async {
  final Handler<MyCustomEvent> successHandler =
      (context, event) async {
    return InvocationResult(context.requestId, "SUCCESS");
  };

  Runtime()
    ..registerEvent<MyCustomEvent>((Map<String, dynamic> json) => MyCustomEvent.from(json))
    ..registerHandler<MyCustomEvent>("doesnt.matter", successHandler)
    ..invoke();
}

Example

The example in main.dart show how the package is intended to be used. Because dart2native does not support cross-platform compilation, you can use the google/dart (:warning: if you are on Linux you can ignore this) container to build the project. The build.sh script automates the build process in the container.

  # will build the binary in the container
  cd example; docker run -v $PWD:/app --entrypoint app/build.sh google/dart && zip lambda.zip bootstrap && rm bootstrap

You will see the lambda.zip which you can upload manually, or use the client of your choice.

What you see in the example is an example of the interface to the Dart Runtime that we created.

You will have to make aws_lambda_dart_runtime a dependency of your project.

...
dependencies:
  aws_lambda_dart_runtime:
...

We support using multiple handlers in one executable. The following example shows to register one handler.

import 'package:aws_lambda_dart_runtime/aws_lambda_dart_runtime.dart';

void main() async {
  /// This demo's handling an API Gateway request.
  final Handler<AwsApiGatewayEvent> helloApiGateway = (context, event) async {
    final response = {"message": "hello ${context.requestId}"};

    /// it returns an encoded response to the gateway
    return InvocationResult(
        context.requestId, AwsApiGatewayResponse.fromJson(response));
  };

  /// The Runtime is a singleton. You can define the handlers as you wish.
  Runtime()
    ..registerHandler<AwsApiGatewayEvent>("hello.apigateway", helloApiGateway)
    ..invoke();
}

This example registers the hello.apigateway handler with the function to execute for this handler. The handler function is typed to receive a Amazon API Gateway Event and it returns a response to the invoking gateway. We support many other events. Handler functions get a Context injected with the needed information about the invocation. You can also register your own custom events via Runtime.registerEvent<T>(Handler<T>) (see events).

Limitations

No Just-in-time (JIT) support
Requires Dart >= 2.6
No cross-platform compile support (see #28617).

Development

If you want to use the Repository directly you can clone it and overwrite the dependency in your pubspec.yaml as follows.

dependency_overrides:
  aws_lambda_dart_runtime:
    path: <path_to_source>

The data folder contains examples of the used events. We use this to run our tests, but you can also use them to implement new features. If you want to request the processing of a new event, you may provide a payload here.

# run the tests
pub run test

License

Apache 2.0

We 💙 Dart.

hewcaw/aws-lambda-dart-runtime