edisongustavo / asl-rust

Rust implementation for Amazon States Language

asl

This library provides an implementation of Amazon States Language (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:

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.

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.

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

ASL is deeply connected to AWS 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 (#9)
States: Task - Hearbeat	Not implemented (#10)
States: Task - Retry	Not implemented (#11)
State: Parallel	Not Implemented (#2)
State: Map	Not Implemented (#1)
Intrinsic Functions	Not Implemented (#4)

License

This project is licensed under the MIT License.

asl-rust's Issues

Improve documentation

Support negative indices in paths

The crate jsonpath-rust doesn't support negative indices. Need a PR to them to add this support.

Remove extra `clone()` calls

Implement heartbeat on Task state

Implement timeout on Task state

ReferencePath: create_new_array_when_index_is_0

Better error messages on execution

Try to mimic the results of Step Functions

Support Parallel state

Remove try_find() method

On https://github.com/edisongustavo/asl-rust/blob/main/src/asl/itertools_utils.rs, there is a poor-man's implementation of iter().try_iter(), which will eventually be stabiliized in rust-lang/rust#63178.

Move to that method when it is ready.

Path definition: Slicing an array that returns a single element, should return an array

See

asl-rust/src/asl/types/core/jsonpath.rs

Lines 146 to 148 in 7be3b1d

	// TODO: This will require having this feature in jsonpath-rust. If the result returned a single
	// element array, then we return the first value. However, in this case this is not desired.
	// #[case::slice_array_of_numbers_only_1_element_left("$.array_of_strings[3:]", json!(["d"]))]

Use if-let chains when they stabilize

Need rust-lang/rust#53667

Implement Intrinsic Functions

Review visibility of structs

As of now, everything is pub.

Implement retries on Task state

Support Map state