aws_lambda_dart_runtime 1.0.3+2

Dart native
Flutter Android iOS

A powerful runtime to build Lambda functions in Dart with native AWS events.

Dart Runtime for AWS Lambda #

Main License Apache 2

The package makes it easy to write AWS Lambda functions in the Dart programming language.

If you want to learn more about the project you can read the introduction.

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 a 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 shipable 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 later 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 #

dependencies:
  aws_lambda_dart_runtime: ^1.0.3+1

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

Future & Ideas #

Limitations #

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

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 (⚠️ 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 to use 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).

Deployment #

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

  1. Compile your Dart program with dart2native main.dart -o bootstrap
  2. Create a .zip file with zip lambda.zip bootstrap
  3. 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

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.

7
likes
90
pub points
63%
popularity

A powerful runtime to build Lambda functions in Dart with native AWS events.

Repository (GitHub)
View/report issues

Documentation

Documentation
API reference

Uploader

sebastian@macpark.de

License

Apache 2.0 (LICENSE)

Dependencies

json_annotation

More

Packages that depend on aws_lambda_dart_runtime