AWS Lambda

BoxLang Runtime for AWS Lambda! Serverless for the win!

What is AWS Lambda?

AWS Lambda is a serverless computing service provided by Amazon Web Services (AWS) that lets you run code without provisioning or managing servers. It automatically scales applications by running code in response to events and allocates compute resources as needed, allowing developers to focus on writing code rather than managing infrastructure (https://docs.aws.amazon.com/lambda/).

The BoxLang AWS Runtime allows you to code in BoxLang and create Lambda functions in this ecosystem. We provide you a nice template so you can work with serverless: https://github.com/ortus-boxlang/bx-aws-lambda-template. This template will give you a turnkey application with features like:

• Unit and Integration Testing

• Java dependency management

• BoxLang depenency management

• Automatic shading and packaging

• GitHub actions to: test, build and release automatically to AWS

https://github.com/ortus-boxlang/bx-aws-lambda-template

BoxLang Lambda Handler

Our BoxLang AWS Handler acts as a front controller to all incoming Lambda executions. It provides you with:

• Automatic request management to an eventstructure

• Automatic logging and tracing

• Execution of your Lambda classes by convention

• Automatic error management

• Automatic response management and serialization

• Life-Cycle Events via our Application.bx

The BoxLang AWS runtime provides a pre-built Java handler for Lambda already configured to accept JSON in as a BoxLang Struct and then output either by returning a simple or complex object or using our response convention struct. Our runtime will automatically convert your results to JSON.

The default handler you configure your lambda with is:

ortus.boxlang.runtime.aws.LambdaRunner::handleRequest

You can see the code for the handler here: https://github.com/ortus-boxlang/boxlang-aws-lambda/blob/development/src/main/java/ortus/boxlang/runtime/aws/LambdaRunner.java#L161

The handler will look for a Lambda.bxin your package and execute the run()method by convention.

Lambda.bx

class {

    function run( event, context, response ){
    
    
    }

}

Environment Variables

The following are all the environment variables the Lambda runtime can read and detect. If they are set by you or the AWS Lambda runner, then it will use those values to alter operations. This doesn't mean that they will exist at runtime, it just means you can set them to alter behavior.

Environmeent	Description
BOXLANG_LAMBDA_CLASS	Absolute path to the lambda to execute. The default path is: /var/task/Lambda.bx Which is your lambda deployed within your zip file.
BOXLANG_LAMBDA_DEBUGMODE	Turn runtime debug mode or not.
BOXLANG_LAMBDA_CONFIG	Absolute path to a custom boxlang.json configuration for the runtime.

You can also leverage ANY env variable to configure the BoxLang runtime using our runtime environment conventions.

BoxLang AWS Template

The BoxLang default template for AWS lambda can be found here: https://github.com/ortus-boxlang/bx-aws-lambda-template. The structure of the project is the following

/.vscode - Some useful vscode tasks and settings
/gradle - The gradle runtime, keep in source control
/src
  + main
    + bx
      + Application.bx (Your life-cycle class)
      + Lambda.bx (Your BoxLang Lambda function)
  + resources
    + boxlang.json (A custom BoxLang configuration file)
    + boxlang_modules (Where you will install BoxLang modules using CommandBox, don't put in source control )
  + test
    + java
      + com
        + myproject
          + LambdaRunnerTest.java (An integration test for your Lambda)
          + TestContext.java (A testing context for lambda)
          + TestLogger.java (A testing logger for lambda)
/workbench - Tons of AWS lambda utilities
/box.json - Your project's dependency descriptor for CommandBox
/build.gradle - The gradle build
/gradle.properties - Where you store your version and metadata
/gradlew - The gradle shell executor, keep in source control
/gradlew.bat - The gradle shell executor, keep in source control
/settings.gradle - The project settings

The BoxLang AWS Lambda runtime will look for a Lambda.bx in your package by convention and execute the run()method for you.

# Download the runtime, later it will be automatic via maven
./gradlew downloadBoxLang

# Run the tests
./gradlew test

# Build the project, create the lambda zip
# The location is /build/distributions/boxlang-aws-project-1.0.0.zip
./gradlew build

# Mess up? No problem, remove the /build folder or run
./gradlew clean

Lambda.bx

The Lambda function is a BoxLang class with a single function called run().

Lambda.bx

/**
 * My BoxLang Lambda
 */
class{

	function run( event, context, response ){
		response.body = {
			"error": false,
			"messages": [],
			"data": "====> Incoming event " & event.toString()
		};
		response.statusCode = 200;
	}
}

Arguments

It accepts three arguments:

Argument	Type	Description
event	Struct	All the incoming JSON as a BoxLang struct
context	com.amazonaws.services.lambda.runtime.Context	The AWS context object. You can find much more information here.
response	Struct	A BoxLang struct convention for a response.

You can find more information about the AWS Context object here: https://docs.aws.amazon.com/lambda/latest/dg/java-context.html

Event

The event structure is a snapshot of the input to your lambda. We deserialize the incoming JSON for you and give you a nice struct.

Context

This is an Amazon Java class that provides extensive information about the request. For more information, check out the API in the Amazon Docs (https://docs.aws.amazon.com/lambda/latest/dg/java-context.html)

Context methods

• getRemainingTimeInMillis() – Returns the number of milliseconds left before the execution times out.

• getFunctionName() – Returns the name of the Lambda function.

• getFunctionVersion() – Returns the version of the function.
• getInvokedFunctionArn() – Returns the Amazon Resource Name (ARN) that's used to invoke the function. Indicates if the invoker specified a version number or alias.

• getMemoryLimitInMB() – Returns the amount of memory that's allocated for the function.

• getAwsRequestId() – Returns the identifier of the invocation request.

• getLogGroupName() – Returns the log group for the function.

• getLogStreamName() – Returns the log stream for the function instance.

• getIdentity() – (mobile apps) Returns information about the Amazon Cognito identity that authorized the request.

• getClientContext() – (mobile apps) Returns the client context that's provided to Lambda by the client application.

• getLogger() – Returns the logger object for the function.

Response

The response argument is our convention to help you build a nice return structure. However, it is completely optional. You can easily return a simple or complex object from your lambda, and we will convert it to JSON.

response : {
  statusCode : 200,
  headers : {
    content-type :  "application/json",
    access-control-allow-origin : "*",
  },
  body : YourLambda.run() results
}

/**
 * My BoxLang Lambda Simple Return
 */
class{

  function run( event, context, response ){
    return "Hello World!"
  }
  
}

/**
 * My BoxLang Lambda Complex Return
 */
class{

  function run( event, context, response ){
    return {
      age : 1,
      when : now(),
      data : [ 12,3234,23423 ]
    };
  }
  
}

Now you can go ahead and build your function. You can use TestBox to unit test your Lambda.bx or we even include a src/test folder in Java, that simulates the full life-cycle of the runtime. Just run gradle test or use VSCode BoxLang IDE to run the tests. Now we go to production!

Multiple Functions Header

The runtime also allows you to create other functions inside of your Lambda that can be targeted if your AWS Lambda is exposed as an URL, which we recommend. You will be able to target different functions in your Lambda.bxby using the following header when executing your lambda:

x-bx-function=methodName

This makes it incredibly flexible where you can respond to that incoming header in a different function than the one by convention.

Lambda Modules

You can use any BoxLang module with the BoxLang Lambda runtime by just installing them to the src/resources/boxlang_modules folder. All modules placed there when running your build script, will be packaged up into your lambda package.

# Using the install-bx-module you can cd to the folder and install modules
cd src/resources
install-bx-module {names} --local

# Or use CommandBox and add them to the box.json
box install id=bx-module directory=src/resources/boxlang_modules

Deploy to AWS

You can deploy your lambda by manually uploading the build package or using our GitHub Action in your template. Below is the action that does an automatic update.

Please note that you MUST create the lambda function in the AWS console FIRST for this to work. This does not create; it only updates.

- name: Update AWS Lambda Function
  uses: kazimanzurrashid/aws-lambda-update-action@v2.0.3
  with:
    zip-file: "./build/distributions/${{ env.PROJECT_NAME }}-${{ env.VERSION }}-all.zip"
    lambda-name: ${{ env.PROJECT_NAME }}-${{ env.DEPLOY_TIER }}
  env:
    AWS_REGION: ${{ secrets.AWS_REGION }}
    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_PUBLISHER_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_PUBLISHER_KEY }}

Our automated approach will require storing your credentials in your repository's secrets.

• AWS_REGION- The region to deploy to

• AWS_PUBLISHER_KEY_ID- The AWS access key

• AWS_SECRET_PUBLISHER_KEY- The AWS secret key

When creating the lambdas, make sure you create two lambdas:

• {projectName}-staging - A staging lambda based on the developmentbranch

• {projectName}-production - A production lambda based on the mainbranch

Please also note that our build process allows you to have a developmentbranch and a master/mainproduction branch. This will enable you to have a deployment of a stagingand a productiontier function in the lambdas console in AWS.

The {projectName}comes from the settings.gradlefile in your root project.

Log in to the Lambda Console and click on Create function button.

AWS Lambda Console

Now let's add the basic information about our deployment:

• Add a function name: {projectName}-staging or production

• Choose Java 21 as your runtime

• Choose x86_64 as your architecture

TIP: If you choose ARM processors, you can save some money.

Create a function

Now, let's upload our test code. You can choose a zip/jar or s3 location. We will do a simple zip from our template:

Upload Test Code

Code Uploaded

Now important, let's choose the AWS Lambda Runtime Handler in the Edit runtime settings

And make sure you use the following handler address: ortus.boxlang.runtime.aws.LambdaRunner::handleRequest This is inside the runtime to execute our Lambda.bx function.

Please note that the RAM you chose for your lambda determines your CPU as well. So make sure you increase the RAM accordingly. We have seen great results with 4GB+.

Testing in AWS

Now click on the Test tab and an event name MyTestEvent. You can also add anything you like in the Event JSON to test the input of your lambda. Then click on Test and watch it do its magic. Now go have some good fun!

Runtime Source Code

The AWS Runtime source code can be found here: https://github.com/ortus-boxlang/boxlang-aws-lambda

We welcome any pull requests, testing, docs, etc.