asl 0.2.0

Rust implementation for Amazon States Language
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

asl
===

[<img alt="crates.io" src="https://img.shields.io/crates/v/asl.svg?logo=rust">](https://crates.io/crates/asl)
[<img alt="docs.rs" src="https://img.shields.io/docsrs/asl?logo=docs.rs">](https://docs.rs/asl)
[<img alt="build status" src="https://img.shields.io/github/actions/workflow/status/edisongustavo/asl/ci.yml?branch=main">](https://github.com/edisongustavo/asl/actions?query=branch%3Amain)

This library provides an implementation of [Amazon States Language](https://states-language.net/) (ASL) in Rust.

The library can parse and execute state machines defined in ASL.

## Example: Hello world

This example will print the strings `Hello` and `World`:

```rust
struct TaskHandler {}
impl StateExecutionHandler for TaskHandler {
    type TaskExecutionError = String;

    fn execute_task(
        &self,
        resource: &str,
        input: &Value,
        credentials: Option<&Value>,
    ) -> Result<Option<Value>, Self::TaskExecutionError> {
        let result = match resource {
            "SayHello" => "Hello",
            "SayWorld" => "World",
            _ => Err("Unknown resource!")?,
        };
        println!("{}", result);
        Ok(None) // We opt into returning nothing
    }
}

fn main() {
    let definition = r#"{
          "Comment": "A simple minimal example of the States language",
          "StartAt": "State: Hello",
          "States": {
            "State: Hello": {
              "Type": "Task",
              "Resource": "SayHello",
              "Next": "State: World"
            },
            "State: World": {
              "Type": "Task",
              "Resource": "SayWorld",
              "End": true
            }
          }
        }"#;
    let state_machine = StateMachine::parse(definition).unwrap();
    let input = Value::Null;
    let execution: Execution<TaskHandler, EmptyContext> = state_machine.start(&input, TaskHandler {}, EmptyContext {});
    // the Execution type implements Iterator, so we can iterate until there are no more states to execute
    let steps: Vec<StateExecutionOutput> = execution.collect();
}
```

See: [test_hello_world.rs](https://github.com/edisongustavo/asl-rust/blob/main/tests/test_hello_world.rs).

## Amazon States Language (ASL)

The Amazon States Language is a JSON-based, structured language used to define your state machine, a collection of states,
that can do work (Task states), determine which states to transition to next (Choice states),
stop an execution with an error (Fail states), and so on.

For a complete definition of ASL, refer to the [Amazon States Language Specification](https://states-language.net/).

**IMPORTANT**: This project is **NOT** affiliated with Amazon in any way.

ASL is deeply connected to [AWS Step Functions](https://docs.aws.amazon.com/step-functions/). This means that in many
places, the definition from the language specification is not specified, so this library opts into following the
results from AWS Step Functions.

## Feature Matrix

The main features that are already implemented or missing are listed in the following table:

| Feature                        | Status                                                                |
|--------------------------------|-----------------------------------------------------------------------|
| State execution workflow       | Implemented                                                           |
| JSON Paths and Reference Paths | Implemented                                                           |
| States: Pass                   | Implemented                                                           |
| States: Wait                   | Implemented                                                           |
| States: Fail                   | Implemented                                                           |
| States: Choice                 | Implemented                                                           |
| States: Succeed                | Implemented                                                           |
| States: Task                   | Implemented, but not all features. See other features in this table.  |
| States: Task - Timeout         | Not implemented (https://github.com/edisongustavo/asl-rust/issues/9)  |
| States: Task - Hearbeat        | Not implemented (https://github.com/edisongustavo/asl-rust/issues/10) |
| States: Task - Retry           | Not implemented (https://github.com/edisongustavo/asl-rust/issues/11) |
| State: Parallel                | Not Implemented (https://github.com/edisongustavo/asl-rust/issues/2)  |
| State: Map                     | Not Implemented (https://github.com/edisongustavo/asl-rust/issues/1)  |
| Intrinsic Functions            | Not Implemented (https://github.com/edisongustavo/asl-rust/issues/4)  |

## License

This project is licensed under the MIT License.