Skip to content

Latest commit

 

History

History
143 lines (113 loc) · 6.4 KB

guide.md

File metadata and controls

143 lines (113 loc) · 6.4 KB

Session Guide

What's in this repository?

This is a sample template for Managing Long Lived Transactions with AWS Step Functions. Below is a brief explanation of what we have created for you:

.
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── docs                    <-- # Workshop guide and setup instructions
├── inventory-release       <-- # Lambda function code represents compensating transaction to release inventory
│   ├── ...
│   └── main.go
├── inventory-reserve       <-- # Lambda function code represents compensating transaction to release inventory
│   ├── ...
│   └── main.go
├── models                  <-- # Models package that defines the types used by the various functions and state data
│   ├── ...
│   ├── inventory.go
│   ├── order.go
│   └── payment.go
├── order-new               <-- # Lambda function code represents task to create a new order and set status to "new order"           
│   ├── ...  
│   └── main.go
├── order-update            <-- # Lambda function code represents compensating transaction for orders. 
│   ├── ...                     # Sets order status to "pending"
│   └── main.go                                
├── payment-credit          <-- # Lambda function code represents the compensating transaction to refund customer order
│   ├── ...
│   └── main.go
├── payment-debit           <-- # Lambda function code represents task to process financial transaction for the order
│   ├── ...
│   └── main.go
├── statemachine
│   └── llt.asl.yaml        <-- # Step Functions ASL template
├── template.yaml           <-- # AWS SAM template for defining and deploying serverless application resources
└── ...

Amazon States Language

A full description of the how to describe your state machine can be found on the Amazon States Language specification.

Please review the "Templates" section in the AWS Console for examples of how you can implement various states.

Useful snippets

Task state

The Task State (identified by "Type":"Task") causes the interpreter to execute the work identified by the state's “Resource” field.

"ProcessOrder": {
  "Comment": "First transaction to save the order and set the order status to new",
  "Type": "Task",
  "Resource": "arn:aws:lambda:[REGION]:[ACCOUNT NUMBER]:function:aws-step-functions-long-lived-tra-NewOrderFunction-121DONKVIBL5T",
  "TimeoutSeconds": 10,
  "Next": "ProcessPayment"
}

Catch

Any state can encounter runtime errors. Errors can arise because of state machine definition issues (e.g. the “ResultPath” problem discussed immediately above), task failures (e.g. an exception thrown by a Lambda function) or because of transient issues, such as network partition events.

"Catch": [
  {
    "ErrorEquals": ["ErrProcessOrder"],
    "ResultPath": "$.error",
    "Next": "UpdateOrderStatus"
  }
]

Retry

Task States and Parallel States MAY have a field named “Retry”, whose value MUST be an array of objects, called Retriers.

When a state reports an error, the interpreter scans through the Retriers and, when the Error Name appears in the value of of a Retrier’s “ErrorEquals” field, implements the retry policy described in that Retrier.

"Retry": [{
  "ErrorEquals": ["States.ALL"],
  "IntervalSeconds": 1,
  "MaxAttempts": 2,
  "BackoffRate": 2.0
  }],
  "Catch": [{
    "ErrorEquals": ["ErrReleaseInventory"],
    "ResultPath": "$.error",
    "Next": "ReleaseInventoryFailed"
  }
]

Custom Errors

The following is a list of all the custom errors thrown by the application and can be used in your state machine.

  • ErrProcessOrder represents a process order error
  • ErrUpdateOrderStatus represents a process order error
  • ErrProcessPayment represents a process payment error
  • ErrProcessRefund represents a process payment refund error
  • ErrReserveInventory represents a inventory update error
  • ErrReleaseInventory represents a inventory update reversal error

Testing Scenarios

The AWS Step Functions implementation has been configured for you to be easily test the various scenarios of the saga implementation. Modifying your order_id with a specified prefix will trigger an error in the each Task.

OrderID Prefix Will error with Example Expected execution
1 ErrProcessOrder 1ae4501d-ed92-4b27-bf0e-fd978ed45127 1
11 ErrUpdateOrderStatus 11328abd-368d-43fd-bd4f-db15b5b63951 11
2 ErrProcessPayment 20b0b599-441b-45c3-910e-ad63fe992c43 2
22 ErrProcessRefund 222f741b-0292-4f93-a2f7-503f92486955 22
3 ErrReserveInventory 3a7dc768-6f32-495d-a140-3d330c246f50 3
33 ErrReleaseInventory 33a49007-a815-4079-9b9b-e30ae7eca11f 3
4-9 No error 47063fe3-56d9-4c51-b91f-71929834ce03 4-9

Invoking your Step Function via CLI

The AWS CLI command will trigger a execution of your state machine. Make sure you substitute the ARN for the state machine in your account. You can find the ARN in the AWS CloudFormation Output section or in the AWS Step Functions console.

CloudFormation Output

--region must match the region you have deployed the application stack into. This is optional if you're using your default region.

aws stepfunctions start-execution \
    --state-machine-arn "arn:aws:states:[REGION]:[ACCOUNT NUMBER]:stateMachine:[STATEMACHINE-NAME]" \
    --input "{\"order_id\": \"40063fe3-56d9-4c51-b91f-71929834ce03\", \"order_date\": \"2018-10-19T10:50:16+08:00\", \"customer_id\": \"8d04ea6f-c6b2-4422-8550-839a16f01feb\", \"items\": [{ \"item_id\": \"567\", \"qty\": 1.0, \"description\": \"Cart item 1\", \"unit_price\": 199.99 }]}" \
    --region [AWS_REGION]

DOWNLOAD SCENARIO CLI COMMANDS

How else can you implement this solution?

Is there any other way you can think of how to break this problem down? What other features of Step Functions could be employed to implement a saga pattern?