@studyportals/sp-r2d2 v5.0.0

R2D2

A bootstrapping framework used to develop Node.js services deployed in AWS Lambda

In this readme you can find explanation about the way R2D2 is set up. When you're done reading and want to get cracking, go to project-template. You'll find a .zip there. Unzip this zip and follow the steps in the README in that zip.

Introduction

R2D2 is a bootstrapper. A bootstrapper is a piece of software that begins the execution of a program, usually carrying out initialization procedures. R2D2 is this, and a little more.

R2D2 aims to enable software engineers to build rich and clearly defined application and domain layers, by taking away the concerns regarding the execution environment or application initialization. It helps software engineers draw a clear line between their application layer and the outside, moving the focus towards the problem domain.

R2D2 is lightweight and flexible, offering the bare minimum functionality necessary to achieve its goal. It carries no additional dependencies and does not enforce the use of the built-in concretions. It heavily employs dependency inversion so that you can provide your own implementations.

R2D2 is open to change. Do you have a use-case that R2D2 is not able to satisfy? Let's discuss to see if R2D2 can be adapted to fit your needs. Did you develop something that could be of use to other R2D2 implementors? Share it and spare us the trouble of reinventing your wheel!

R2D2 is backed by an extensive regression suite. Given R2D2's crucially role in the inner workings of your service, we need to make sure that it works exactly the way we've engineered it.

R2D2 is out there. R2D2 is powering House Stark's backend services and many others. It had been maturing alongside them and shortcomings have been ironed out as development progressed.

R2D2 is developed in TypeScript. Node.js is a reliable runtime, arguments can be made to support the usage of JavaScript in back-end services, however, the prototype-oriented nature of JavaScript makes it unable to carry the burden of the elaborate design of your back-end services. There's a reason why the Object Oriented paradigm has been around for so long and why it's not going anywhere. By using TypeScript in the development of R2D2, we hope you'll be encouraged to also make the transition. Don't like TypeScript? No problem, R2D2 is distributed as JavaScript binaries, so that you can use it in your JavaScript service as well!

Layers

R2D2 uses various layers to group cohesive elements of its design. As usual, the rule in layered designs is that a horizontal layer may only access elements in the layer directly under itself, upwards dependencies are prohibited as they would decrease the layer's abstraction.

R2D2's design consists of two main layers: the Environment layer and the Application layer, with an additional vertical layer, the Infrastructure layer.

Environment Layer

The Environment layer handles the interaction between your service and the environment. It bridges the gap between your application level protocol and the transmission level protocol. It reaches to the Application layer to trigger the execution of the Lambda Event as a Request and sends the execution outcome back to the initiator.

Application - Transmission Protocol Translation

In order to shield your Application layer from the execution environment, R2D2 handles the translation to and from the Transmission protocol.

Lambda Event to Request Translation

A Request is a Command (Gamma, et al., 1995) handled by the Application layer.

To keep it as general as possible, by default, the Request only exposes one property, used to aquire the request's data. An additional concrete class is built into R2D2, BaseAuthenticatedRequest, intended to be used when the identity of the initiator is available.

The translation is handled by the IEventTranslator element.

The way the translation is handled depends on the execution environment and your application protocol. Event Translators are available for the built-in Request concretions, for all the supported environments. Feel free to define your own, to fit the needs of your service!

Execution Outcome Translation

The outcome of a Request execution is translated back to the transmission protocol by the IResponseSender element.

Context about the outcome is provided by executing the appropriate method and through the Error classes defined by the Application layer. The way the translation is handled depends on the execution environment and your application protocol. Response Senders are defined for all the supported environments. Feel free to define your own, to fit the needs of your service!

Application Layer

TBD

Infrastructure Layer

The Infrastructure layer provides various bits and pieces that you may need while developing your service. One of the most important element is the IEnvironmentVariablesProvider.

The Environment Variables Provider allows you to acquire the value of various environment variables. Two concrete implementations are provided, one that acquires the environment variables from the process global available from within AWS Lambda, and the EnvironmentVariablesCatalog, used to pre-configure a set of environment variables, mainly for testing purposes.

Bootstrapping

Bootstrapping is handled by the IBootstrapper element, available in the Environment layer. A Bootstrapper must be able to run initialization operations and to clean-up any unmanaged resources. The Bootstrapper may use a Response Sender to intermediate the communication with the initiator, in exceptional cases, such as uncaught exceptions handling.

Bootstrapping an AWS Lambda service must account for the fact that the same AWS Lambda Container may be used for multiple invocations. This is an advantage, as expensive initialization operations do not have to be repeated every time the AWS Lambda Function is invoked, but may catch you off guard if you do not take the necessary measures to ensure that the bootstrapping sequence is safely repeatable after the clean-up operations are carried out.

R2D2's built in bootstrapper accounts for this aspect by spliting the bootstrapping sequence in two steps. The first step configures the environment - in other words, it carries out bootstrapping operations that should be re-used between subsequent invocations - while the second step configures the instance - it carries out bootstrapping operations that are only applicable to the current call. When using the built in bootstrapper, you must ensure that the bootstrapping operations carried out during the instance configuration stepts are repeatable after the clean-up operations are carried out.

R2D2's built in bootstrapper also installs global handlers for uncaught errors or Promise rejections, replacing any existing handlers.

The Lambda Handler

TBD

Pings

If you've ever developed an AWS Lambda service that does not get a lot of usage, you've known the pain of waiting for the Lambda containers to "warm up", and you've probably solved that by pinging your Lambda functions so that at least one container would be "warm" at all times.

R2D2's offers a built-in mechanism to handle ping events without having them reach the Application layer. To ping R2D2 backed Lambda Functions using the built-in protocol, specify the following event:

{
    "___PING___": 1
}

You will receive the following response:

{
    "___PONG___": 1
}

Don't like the built in protocol? Feel free to define your own, so that it fits your service's needs!

Execution Environments

R2D2 can be extended to support any AWS Lambda Trigger. Some of the built-in execution environments are:

• API Gateway
• SNS
• SQS
• Scheduler

Not quite what you need? Help us by building the translation elements for your target environment and make them part of R2D2!

Recommandations

TBD