Repository files navigation

This package provides an R runtime interface client for theAWS Lambdaserverless compute service. It makes itpossible to deploy code written in R asLambda functions when using containerimages.

This package isunofficial. Its creators are not affiliated withAmazon Web Services, nor is its content endorsed byAmazon Web Services.Lambda,API Gateway,EventBridge,CloudWatch, andSNS are services ofAmazon Web Services.

Any programming language can be used to create a container-based Lambdafunction. All that's required is a language-specific runtime. AWS provides suchruntimes for a handful of languages, e.g. Python, Go, and Ruby - but not for R.

As a runtime for R,lambdr's job is to coordinate the translation and transferof inputs/responses between the outside world and an invoked Lambda'shandlerfunction.

The default behaviour is to convert the body of the received event from JSONinto arguments for the Lambda'shandler function using thejsonlite package.

For example, a raw event body of{"number": 9} will be converted tolist(number = 9). The handler function will then receive the argumentsdirectly after unlisting, eg.number = 9. This works for direct invocations,as well as situations where the user wishes to implement behaviour specific toa trigger.

Some invocation types have their own logic for converting the event body intoan R object. This is useful for say, using an R function in a Lambda behindan API Gateway, so that the R function does not need to deal with the HTMLelements of the invocation. The below invocation types have custom logicimplemented. Refer to the vignettes or the package website for moreinformation.

Alternatively, user-defined functions can be provided for parsing eventcontent and serialising results. The user can also use theidentityfunction as a deserialiser to pass the raw event content --- as a string ---to the handler function. Refer to?lambda_config for more information.

invocation type	implementation stage
direct
API Gateway (REST)
API Gateway (HTML)
EventBridge
SNS

The package can be installed from CRAN with:

install.packages("lambdr")

The development version is available with:

remotes::install_github("mdneuzerling/lambdr")

In aruntime.R file, source all functions needed and then run:

lambdr::start_lambda()

Thisruntime.R file should be executed by the Docker image containing yourLambda code.

Thelambdr::start_lambda() function relies on environment variablesconfigured by AWS. It will fail if run locally. In particular, thehandler asconfigured by the user through AWS will determine which function handles theLambda events. For debugging and testing, values can be provided to the function in the absence of environment variables. See?lambdr::lambda_config fordetails.

Consider the followingruntime.R file:

parity<-function(number) {list(parity=if (as.integer(number)%%2==0)"even"else"odd")}lambdr::start_lambda()

Theparity function accepts anumber argument and returns its parity as a named list, for example:

parity(5)# $parity# [1] "odd"parity(8)# $parity# [1] "even"

This function can then be placed into a Docker image. Anexample Dockerfile is provided below, but the key components are:

• Start from a minimal Rocker parent image (not the Rocker tidyverse image)
• Install package dependencies usingpak, which also handles system dependencies.
• Copy acrossruntime.R and any other necessary files
• Set the handler as theCMD. Thelambdr package interprets the handler as the name of the function to use, in this case, "parity". TheCMD can also be set (or overriden) when setting up the Lambda in AWS.

FROM docker.io/rocker/r-ver:4.4# curl is required for {pak}RUN apt-get update && apt-get -y install --no-install-recommends curl# options(warn=2) will make the build error out if package doesn't installRUN Rscript -e"options(warn = 2); install.packages('pak')"# Using {pak} to install R packages: it resolves Ubuntu system dependencies AND# the R dependency tree. Other required packages can be installed here.RUN Rscript -e"pak::pak('lambdr')"RUN mkdir /RCOPY runtime.R /RRUN chmod 755 -R /RENTRYPOINT Rscript R/runtime.RCMD ["parity"]

The image is built and uploaded to AWS Elastic Container Registry (ECR). First, a repository is created:

aws ecr create-repository --repository-name parity-lambda --image-scanning-configuration scanOnPush=true

This provides a URI, the resource identifier of the created repository. The image can now be pushed:

docker build --platform linux/amd64 -t r-on-lambda. docker tag mdneuzerling/r-on-lambda:latest {URI}/parity-lambda:latestaws ecr get-login-password| docker login --username AWS --password-stdin {URI}docker push {URI}/parity-lambda:latest

In either the AWS console or the command line, a Lambda can be created from this image. Call the Lambda "parity" to match the function name. Tests can be executed within the console. Alternatively the Lambda can be invoked from the CLI:

aws lambda invoke --function-name parity \  --invocation-type RequestResponse --payload'{"number": 8}' \  /tmp/response.json --cli-binary-format raw-in-base64-out

The output is now available in the generated file:

cat /tmp/response.json

{"parity":"even"}

A detailed guide on how to create these Dockerfiles, as well as a guide for those new to Docker, can be found in the vignettes.

Hex logo by Phizz Leeder