@vibou/serverless-step-functions-offline
v3.1.2
Published
Serverlesss plugin to support step function offline
Downloads
130
Maintainers
Readme
Documentation
Install
Using NPM:
npm install @vibou/serverless-step-functions-offline serverless-step-functions serverless-offline serverless --save-dev
or Yarn:
yarn add @vibou/serverless-step-functions-offline serverless-step-functions serverless-offline serverless --dev
Setup
Add the plugin to your serverless.yml
:
# serverless.yml
plugins:
- serverless-offline
- serverless-step-functions
- '@vibou/serverless-step-functions-offline'
To verify that the plugin works, run this in your command line:
sls step-functions-offline
It should rise an error like that:
Serverless plugin "serverless-step-functions-offline" initialization errored: Please add ENV_VARIABLES to section "custom"
Requirements
This plugin uses the power of serverless-offline
and awscli
to run the lambda within the step function. The plugin
can be used with any kind of serverless-offline runtime compatible lambda.
This plugin works only with:
You must have this plugin installed and correctly specified statemachine definition using Amazon States Language. You need the
Example of statemachine definition you can see here.
Usage
After all steps are done, need to add to section custom in serverless.yml the key stepFunctionsOffline with properties stateName: name of lambda function.
For example:
service: ServerlessStepPlugin
plugins:
- serverless-offline
- serverless-step-functions
- '@vibou/serverless-step-functions-offline'
# ...
custom:
stepFunctionsOffline:
Producer: producer
Reducer: reducer
Finish: reducer
MappingFunction: mapper
functions:
producer:
handler: build/function/workflow/producer/index.handler
timeout: 30
mapper:
handler: build/function/workflow/mapper/index.handler
timeout: 300
reducer:
handler: build/function/workflow/reducer/index.handler
timeout: 300
stepFunctions:
stateMachines:
mapReduceExample:
definition:
Comment: 'MapReduceExample'
StartAt: Producer
States:
Producer:
Type: Task
Resource: arn:aws:lambda:eu-west-1:123456789:function:producer
ResultPath: '$.producer'
Next: Mapper
Mapper:
Type: Map
Next: Reducer
ItemsPath: '$.producer.requests'
Parameters:
input.$: '$.input'
producer.$: '$.producer'
item.$: '$$.Map.Item.Value'
MaxConcurrency: 10
ResultPath: '$.mapper'
Iterator:
StartAt: MappingFunction
States:
MappingFunction:
Type: Task
Resource: arn:aws:lambda:eu-west-1:123456789:function:mapper
End: true
Reducer:
Type: Task
Resource: arn:aws:lambda:eu-west-1:123456789:function:reducer
ResultPath: '$.reducer'
End: true
Run Plugin
Run the workflow
I recommand to add the following script to the package.json
.
"scripts": {
"start": "sls offline start",
"workflow": "sls step-functions-offline --stateMachine=mapReduceExample --lambdaEndpoint http://localhost:3002",
}
You need to start a serverless server in one terminal:
yarn start
And start a workflow execution by using the following command:
yarn workflow --event=<input.json>
Run the workflow using the AWS-SDK from a lambda function
Add the workflow
command from the previous section and add the following dependency.
yarn add -D aws-sdk-mock
mock the AWS Service when working offline:
import { AWSError, StepFunctions } from 'aws-sdk'
import fs from 'fs'
type Callback<T = any> = (err: AWSError | null, output: T) => void
export function MockLocalServices(awsSDK) {
if (!isOffline()) return
const AWSMock = require('aws-sdk-mock')
AWSMock.setSDKInstance(sdk)
AWSMock.mock(
'StepFunctions',
'startExecution',
(
params: StepFunctions.StartExecutionInput,
cb: Callback<StepFunctions.Types.StartExecutionOutput>,
) => {
// save input to file
const file = `/tmp/stepfunction-${v4()}.json`
fs.writeFileSync(file, params.input || JSON.stringify({}))
// run child process with the yarn command
execute('yarn', ['workflow', `--event=${file}`], {}, true).then(() =>
cb(null, {
executionArn: v4(),
startDate: new Date(),
}),
)
}
}
Here is the code for the execute
function:
import { SpawnOptionsWithoutStdio, spawn } from 'child_process';
export async function execute(
process: string,
args: string[],
options?: SpawnOptionsWithoutStdio,
logOutput = false
): Promise<string> {
return new Promise((r, f) => {
const execution = spawn(process, args, options);
let error: Error | null = null;
let dataStr = '';
execution.stdout.on('data', data => {
if (logOutput) {
console.log(data.toString().replace(/\n$/, ''));
}
dataStr += data.toString();
});
execution.stderr.on('error', err => {
error = err;
});
execution.stderr.on('data', data => {
console.log(data.toString().replace(/\n$/, ''));
});
execution.on('close', code => {
if (error) {
f(error);
return;
}
if (code) {
return f(new Error('failed with code ' + code));
}
r(dataStr);
});
});
}
Other Information
IS_OFFLINE information
If you want to know where you are (in offline mode or not) you can use env variable STEP_IS_OFFLINE
.
By default process.env.STEP_IS_OFFLINE = true
.
What does plugin support?
| States | Support | | -------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Task | Supports Retry, ResultsPath but at this moment does not support fields Catch, TimeoutSeconds, HeartbeatSeconds | | Choice | All comparison operators except: And, Not, Or | | Wait | All following fields: Seconds, SecondsPath, Timestamp, TimestampPath | | Parallel | Only Branches | | Map | Supports Iterator and the following fields: ItemsPath, ResultsPath, Parameters, MaxConcurrency | | Pass | Result, ResultPath | | Fail | Cause, Error | | Succeed | |