Metadata-Version: 2.1
Name: cdk-stepfunctions-patterns
Version: 0.1.5
Summary: A set of Step Functions high-level patterns.
Home-page: https://github.com/kolomied/cdk-stepfunctions-patterns#readme
Author: Dmitry Kolomiets<kolomied@amazon.co.uk>
License: MIT
Project-URL: Source, https://github.com/kolomied/cdk-stepfunctions-patterns.git
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Typing :: Typed
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: aws-cdk.aws-lambda (==1.49.1)
Requires-Dist: aws-cdk.aws-stepfunctions-tasks (==1.49.1)
Requires-Dist: aws-cdk.aws-stepfunctions (==1.49.1)
Requires-Dist: aws-cdk.core (==1.49.1)
Requires-Dist: constructs (<4.0.0,>=3.0.4)
Requires-Dist: jsii (<2.0.0,>=1.12.0)
Requires-Dist: publication (>=0.0.3)

# cdk-stepfunctions-patterns

![build](https://github.com/kolomied/cdk-stepfunctions-patterns/workflows/build/badge.svg)
![jsii-publish](https://github.com/kolomied/cdk-stepfunctions-patterns/workflows/jsii-publish/badge.svg)
![downloads](https://img.shields.io/npm/dt/cdk-stepfunctions-patterns)

[![npm version](https://badge.fury.io/js/cdk-stepfunctions-patterns.svg)](https://badge.fury.io/js/cdk-stepfunctions-patterns)
[![PyPI version](https://badge.fury.io/py/cdk-stepfunctions-patterns.svg)](https://badge.fury.io/py/cdk-stepfunctions-patterns)
[![NuGet version](https://badge.fury.io/nu/Talnakh.StepFunctions.Patterns.svg)](https://badge.fury.io/nu/Talnakh.StepFunctions.Patterns)

*cdk-stepfunctions-patterns* library is a set of [AWS CDK](https://aws.amazon.com/cdk/) constructs that provide
resiliency patterns implementation for AWS Step Functions.

All these patterns are *composable*, meaning that you can combine them together to create
quite complex state machines that are much easier to maintain and support than low-level
JSON definitions.

* [Try / Catch](#try--catch-pattern)
* [Try / Finally](#try--finally-pattern)
* [Try / Catch / Finally](#try--catch--finally-pattern)
* [Retry with backoff and jitter](#retry-with-backoff-and-jitter)
* [Resilience lambda errors handling](#resilience-lambda-errors-handling)
* [Validation of proper resilience lambda errors handling](#validation-of-proper-resilience-lambda-errors-handling)

## Try / Catch pattern

Step Functions support **Try / Catch** pattern natively with [Task](https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-task-state.html)
and [Parallel](https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-parallel-state.html) states.

`TryTask` construct adds a high level abstraction that allows you to use Try / Catch pattern with any state or sequence of states.

### Example

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
import aws_cdk.aws_stepfunctions as sfn
from cdk_stepfunctions_patterns import TryTask

# ...

sfn.StateMachine(self, "TryCatchStepMachine",
    definition=TryTask(self, "TryCatch",
        try_process=sfn.Pass(self, "A1").next(sfn.Pass(self, "B1")),
        catch_process=sfn.Pass(self, "catchHandler"),
        # optional configuration properties
        catch_props={
            "errors": ["Lambda.AWSLambdaException"],
            "result_path": "$.ErrorDetails"
        }
    )
)
```

### Resulting StepFunction

![](doc/tryCatch.png)

## Try / Finally pattern

It is often useful to design state machine using **Try / Finally** pattern. The idea is to have a *Final* state that has to be
executed regardless of successful or failed execution of the *Try* state. There may be some temporal resource you want
to delete or notification to send.

Step Functions do not provide a native way to implement that pattern but it can be done using
[Parallel](https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-parallel-state.html) state and *catch all* catch
specification.

`TryTask` construct abstracts these implementation details and allows to express the pattern directly.

### Example

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
import aws_cdk.aws_stepfunctions as sfn
from cdk_stepfunctions_patterns import TryTask

# ...

sfn.StateMachine(self, "TryFinallyStepMachine",
    definition=TryTask(self, "TryFinally",
        try_process=sfn.Pass(self, "A2").next(sfn.Pass(self, "B2")),
        finally_process=sfn.Pass(self, "finallyHandler"),
        # optional configuration properties
        finally_error_path="$.FinallyErrorDetails"
    )
)
```

### Resulting StepFunction

![](doc/tryFinally.png)

## Try / Catch / Finally pattern

This is a combination of two previous patterns. `TryTask` construct allows you to express rather complex
error handling logic in a very compact form.

### Example

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
import aws_cdk.aws_stepfunctions as sfn
from cdk_stepfunctions_patterns import TryTask

# ...

sfn.StateMachine(self, "TryCatchFinallyStepMachine",
    definition=TryTask(self, "TryCatchFinalli",
        try_process=sfn.Pass(self, "A3").next(sfn.Pass(self, "B3")),
        catch_process=sfn.Pass(self, "catchHandler3"),
        finally_process=sfn.Pass(self, "finallyHandler3")
    )
)
```

### Resulting StepFunction

![](doc/tryCatchFinally.png)

## Retry with backoff and jitter

Out of the box Step Functions retry implementation provides a way to configure backoff factor,
but there is no built in way to introduce jitter. As covered in
[Exponential Backoff And Jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)
and [Wait and Retry with Jittered Back-off](https://github.com/Polly-Contrib/Polly.Contrib.WaitAndRetry#wait-and-retry-with-jittered-back-off) this retry technique can be very helpful in high-load
scenarios.

`RetryWithJitterTask` construct provides a custom implementation of retry with backoff and
jitter that you can use directly in your state machines.

### Example

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
import aws_cdk.aws_stepfunctions as sfn
from cdk_stepfunctions_patterns import RetryWithJitterTask

# ...

sfn.StateMachine(self, "RetryWithJitterStepMachine",
    definition=RetryWithJitterTask(self, "AWithJitter",
        try_process=sfn.Pass(self, "A4").next(sfn.Pass(self, "B4")),
        retry_props={"errors": ["States.ALL"], "max_attempts": 3}
    )
)
```

### Resulting StepFunction

![](doc/retryWithJitter.png)

## Resilience lambda errors handling

`LambdaInvoke` construct from [aws-stepfunctions-tasks](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-stepfunctions-tasks-readme.html)
module is probably one of the most used ones. Still, handling of
[AWS Lambda service exceptions](https://docs.aws.amazon.com/step-functions/latest/dg/bp-lambda-serviceexception.html)
is often overlooked.

`ResilientLambdaTask` is a drop-in replacement construct for `LambdaInvoke` that adds retry for the most common
transient errors:

* Lambda.ServiceException
* Lambda.AWSLambdaException
* Lambda.SdkClientException
* Lambda.TooManyRequestsException

### Example

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
import aws_cdk.aws_lambda as lambda_
from cdk_stepfunctions_patterns import ResilientLambdaTask

# ...

lambda_function = lambda_.Function(self, "LambdaFunction")

calculate_jitter_task = ResilientLambdaTask(self, "InvokeLambda",
    lambda_function=lambda_function
)
```

That would result in the following state definition:

```json
"InvokeLambda": {
    "Type": "Task",
    "Resource": "arn:aws:states:::lambda:invoke",
    "Parameters": {
        "FunctionName": "<ARN of lambda function>"
    },
    "Retry": [{
        "ErrorEquals": [
        "Lambda.ServiceException",
        "Lambda.AWSLambdaException",
        "Lambda.SdkClientException",
        "Lambda.TooManyRequestsException"
        ],
        "IntervalSeconds": 2,
        "MaxAttempts": 6,
        "BackoffRate": 2
    }]
}
```

## Validation of proper resilience lambda errors handling

It is often a challenge to enforce consistent transient error handling across all state machines of a large
application. To help with that, *cdk-stepfuctions-patterns* provides a [CDK aspect](https://docs.aws.amazon.com/cdk/latest/guide/aspects.html)
to verify that all Lambda invocations correctly handle transient errors from AWS Lambda service.

Use `ResilienceLambdaChecker` aspect as shown below.

### Example

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
import aws_cdk.core as cdk
from cdk_stepfunctions_patterns import ResilienceLambdaChecker

app = cdk.App()
# ...

# validate compliance rules
app.node.apply_aspect(ResilienceLambdaChecker())
```

If there are some states in your application that do not retry transient errors or miss some recommended
error codes, there will be warning during CDK synthesize stage:

```
PS C:\Dev\GitHub\cdk-stepfunctions-patterns> cdk synth --strict
[Warning at /StepFunctionsPatterns/A] No retry for AWS Lambda transient errors defined - consider using ResilientLambdaTask construct.
[Warning at /StepFunctionsPatterns/B] Missing retry for transient errors: Lambda.AWSLambdaException,Lambda.SdkClientException.
```


