Getting Started

Prerequisites

To use Stepper, you will need the Java JRE (version 8 or above). If you want the compiler to automatically install the supporting Lambda and Step Function, you will need your AWS credentials setup using one of the mechanisms described below. The credentials should be for an IAM account that has permissions to create Lambda and Step Functions. Credentials can be supplied using (excerpt from from AWS SDK):

• Java System Properties - aws.accessKeyId and aws.secretKey
• Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
• Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
• Credentials delivered through the Amazon EC2 container service if AWS_CONTAINER_CREDENTIALS_RELATIVE_URI" environment variable is set and security manager has permission to access the variable,
• Instance profile credentials delivered through the Amazon EC2 metadata service

The Compiler

Download the Stepper executable from maven:

https://search.maven.org/remotecontent?filepath=com/eclecticlogic/stepper/0.9.0/stepper-0.9.0-shade.jar This contains the Stepper compiler. To compile you Stepper code, run the following command:

> java -jar stepper-<version>-shaded.jar [options] <stepper program file>
  Options:
    -i, --install
      Compiles and installs Step Function ASL and Lambda using information 
      provided in yaml file.

Manual mode

Lets see the process in action with a simple Stepper file:

stepper HelloWorld {
	output = "Hello World";
}	

Save the above code as helloworld.stepper. Run the following command:

> java -jar stepper-0.9.0-shaded.jar helloworld.stepper
Wrote asl to HelloWorld.asl

The step function ASL is written to the same directory as the Stepper program.

HelloWorld.asl
{  
  "StartAt": "HelloWorld000",  
  "States": {  
    "HelloWorld000": {  
      "Type": "Pass",  
      "Result": "Hello World",  
      "ResultPath": "$.output",  
      "Next": "HelloWorld.Success"  
    },  
    "HelloWorld.Success": {  
      "Type": "Succeed"  
    }  
  }  
}

The simple step function that we ran did not need a supporting Lambda. If it did, a HelloWorld.js file would also have been created. You would then need to manually create the Lambda and then replace any references to @@@lambda_helper_arn@@@ with the arn for the Lambda.

Automatic mode

To have the Stepper compiler automatically setup your ASL and supporting Lambda, ensure that your AWS credentials are setup as described in the Prerequisites above. Then create a yaml file with information to support the install:

stepFunction:
  executionRole: "arn:aws:iam::1570xxx:role/service-role/stepFunctionRole"

lambda:
  executionRole: "arn:aws:iam::1570xxx:role/lambda_basic_execution"

The yaml file specifies the ARN of the role that the Step Function should execute under. This role should have permissions to any resources that the Step Function invokes (SQS, Activity, DynamoDB, etc). The file also specifies the role for the supporting Lambda to execute in. This can be minimal as the supporting Step Function does not invoke any external resources. Since you cannot create a role with no permissions, a minimum role such as the one shown below should suffice.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "logs:PutLogEvents",
            "Resource": "arn:aws:logs:*:*:*"
        }
    ]
}

We will now attempt to create a Step Function and have the compiler setup the Lambda and ASL for us. The Stepper code below computes the square root of an input.

stepper SquareRoot {
	output = Math.sqrt(input);
}

Setup your yaml file and run the following command:

> java -jar stepper-shade.jar --install setup.yaml squareroot.stepper
Lambda installed. Arn = arn:aws:states:us-east-1:1570xxx:stateMachine:SquareRoot

The compiler creates a Lambda function called SquareRoot_stepperLambda and then creates a Step Function called SquareRoot (derived from the Stepper program name). The Step Function created looks like this.

{
  "StartAt": "SquareRoot000",
  "States": {
    "SquareRoot000": {
      "Type": "Task",
      "Parameters": {
        "cmd__sm": "SquareRoot000",
        "input.$": "$.input"
      },
      "ResultPath": "$.output",
      "Resource": "arn:aws:lambda:us-east-1:1570xxx:function:SquareRoot_stepperLambda",
      "Next": "SquareRoot.Success"
    },
    "SquareRoot.Success": {
      "Type": "Succeed"
    }
  }
}

The Lambda handles the actual square root computation:

exports.handler = async (event) => {
        if (event.cmd__sm == "SquareRoot000") {
            var input = event.input;

            const response = Math.sqrt(input);
            return response;
        }

    else return {"error": "no branch matched"};
};

Given an input of

{
  "input": 9
}

the Step Function above produces the following output:

{
  "input": 9,
  "output": 3
}