Skip to content

Latest commit

 

History

History
204 lines (160 loc) · 11.8 KB

feature-support.md

File metadata and controls

204 lines (160 loc) · 11.8 KB
Raw

Feature support

Table of contents

Spec features

The following features all come from the Amazon States Language specification.

Fully supported

  • Top-level fields
    • TimeoutSeconds
  • Input processing
    • InputPath
    • Parameters
  • Output processing
    • ResultSelector
    • ResultPath
    • OutputPath
  • States
    • Succeed
    • Pass
      • Result
    • Wait
      • Seconds
      • SecondsPath
      • Timestamp
      • TimestampPath
    • Task
      • Resource (only Lambda functions supported)
      • TimeoutSeconds
      • TimeoutSecondsPath
    • Parallel
      • Branches
    • Map
      • Iterator
      • ItemProcessor
      • Parameters
      • ItemSelector
      • ItemsPath
      • MaxConcurrency
      • MaxConcurrencyPath
    • Fail
      • Error
      • ErrorPath
      • Cause
      • CausePath
      • Terminate execution with error
    • Choice
      • Boolean expressions
        • And
        • Or
        • Not
      • Data-test expressions
        • StringEquals, StringEqualsPath
        • StringLessThan, StringLessThanPath
        • StringGreaterThan, StringGreaterThanPath
        • StringLessThanEquals, StringLessThanEqualsPath
        • StringGreaterThanEquals, StringGreaterThanEqualsPath
        • StringMatches
        • NumericEquals, NumericEqualsPath
        • NumericLessThan, NumericLessThanPath
        • NumericGreaterThan, NumericGreaterThanPath
        • NumericLessThanEquals, NumericLessThanEqualsPath
        • NumericGreaterThanEquals, NumericGreaterThanEqualsPath
        • BooleanEquals, BooleanEqualsPath
        • TimestampEquals, TimestampEqualsPath
        • TimestampLessThan, TimestampLessThanPath
        • TimestampGreaterThan, TimestampGreaterThanPath
        • TimestampLessThanEquals, TimestampLessThanEqualsPath
        • TimestampGreaterThanEquals, TimestampGreaterThanEqualsPath
        • IsNull
        • IsPresent
        • IsNumeric
        • IsString
        • IsBoolean
        • IsTimestamp
      • Throw States.NoChoiceMatched error if no choice rule was matched and Default
  • Intrinsic functions
    • States.Format
    • States.StringToJson
    • States.JsonToString
    • States.Array
    • States.ArrayPartition
    • States.ArrayContains
    • States.ArrayRange
    • States.ArrayGetItem
    • States.ArrayLength
    • States.ArrayUnique
    • States.Base64Encode
    • States.Base64Decode
    • States.Hash
    • States.JsonMerge
    • States.MathRandom
    • States.MathAdd
    • States.StringSplit
    • States.UUID
  • Errors
    • Runtime errors
      • Predefined error codes
    • Retry
      • MaxDelaySeconds
      • JitterStrategy
    • Catch

Not supported

  • States
    • Task
      • HeartbeatSeconds
      • HeartbeatSecondsPath
      • Credentials
    • Map
      • Distributed mode
      • ItemReader
      • ItemBatcher
      • ResultWriter
      • ToleratedFailurePercentage
      • ToleratedFailureCount

Non-spec features

The following features are not defined in the specification, but they have been added for convenience.

Task state resource override

aws-local-stepfunctions has the ability to invoke Lambda functions specified in the Resource field of Task states, provided that you have the necessary AWS credentials. No other service integrations are currently available.

However, if you want to be able to run a state machine completely locally (no matter the type of Resource specified) you can specify a local function to be called in place of the resource. This is accomplished through the overrides.taskResourceLocalHandlers option of the StateMachine.run method. This option expects an object that maps state names to an overriding local function.

The overriding function will receive the processed input of its Task state as the first argument. The return value of said function will be the result of the state (but not its output, which as defined in the spec, depends on further processing done by the ResultSelector, ResultPath and OutputPath fields).

Effectively, task resource overrides allow aws-local-stepfunctions to execute state machines without calls to any AWS service, if you override all of the Task states in the state machine definition.

An example usage of this feature can be found here.

Wait state duration override

As defined by the spec, Wait states in aws-local-stepfunction will pause the state machine execution until the specified Seconds have elapsed or the specified Timestamp has been reached.

Nonetheless, if you want to override the duration of the wait period of a Wait state, you can do so by specifying the overrides.waitTimeOverrides option of the StateMachine.run method. This option expects an object that maps state names to numbers, where the number represents the amount of milliseconds that the overridden Wait state will pause the execution for. Note that you may pass 0 for the number value, which effectively means that the overridden Wait state will not pause the execution at all.

An example usage of this feature can be found here.

Retry field interval override

As defined by the spec, retriers in a Retry field will pause the execution for a certain amount of time before retrying the failed Task/Parallel/Map state, based on the IntervalSeconds, BackoffRate, MaxDelaySeconds, and JitterStrategy fields.

If you wish to override the duration of this pause, you can do so by specifying the overrides.retryIntervalOverrides option of the StateMachine.run method. This option expects an object that maps state names to numbers or arrays:

  • If you pass a number as value, this value represents the number of milliseconds that the overridden Retry field will pause the execution for. This applies to all retriers in the array.
  • If you pass an array as value, each value in the array should be a number and it represents how many milliseconds to pause the execution for the retrier at that index, i.e., the value at index 0 applies for the retrier at index 0, the value at index 1 applies for the retrier at index 1, and so forth. If don't want to override a retrier, simply set the value to -1, to indicate that the retrier at that index should not be overridden.

In a similar fashion to the Wait state duration override, you can pass a duration of 0 to indicate that the overridden retrier should not pause the execution at all before retrying the failed state.

An example usage of this feature can be found here.

Abort a running execution

If for some reason you need to abort an execution in progress, you can do so by calling the abort method that is part of the object returned by the StateMachine.run method.

By default, aborting an execution will throw an error of type ExecutionAbortedError, which you can catch and compare against using instanceof. A demonstration of this behavior can be found in this example.

If instead you prefer to abort an execution without throwing an error, you can pass the noThrowOnAbort option to the StateMachine.run method. When this option is true, aborting an execution will simply return null as result. Likewise, an example demonstrating this behavior can be found here.

Providing AWS credentials and region to execute Lambda functions specified in Task states

NOTE: If you have overridden all Task states in your state machine with local functions, you don't need to specify any AWS credentials or region.

When using aws-local-stepfunctions on Node, you don't need to specify AWS credentials explicitly, as those will be automatically loaded from the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables or from the shared credentials file, as described in the AWS JavaScript SDK docs.

Similarly, you don't need to specify the AWS region, as it will also be automatically loaded, in this case from the AWS_REGION environment variable or from the shared config file, as described in the SDK docs.

However, when using aws-local-stepfunctions in the browser you must provide AWS credentials, otherwise the aws-local-stepfunctions will not be able to invoke the Lambda functions and the execution will fail.

To provide credentials and region, specify the stateMachineOptions.awsConfig option in the StateMachine constructor. You can set two types of credentials:

  1. Access Keys: Access Key ID and Secret Access Key (example).
  2. Cognito Identity Pool: The ID of a Cognito Identity Pool (example).

Make sure that the IAM user/role associated with the access keys or Cognito Identity Pool have the necessary policies to be able to invoke the Lambda functions referenced in your state machine definition.

Execution event logs

During the course of an execution, the state machine goes through several events, such as transitioning into different states, or performing the action that corresponds to each type of event. Naturally, these events happen until the execution terminates, either by reaching the end state, encountering an error and failing, being aborted or timing out.

aws-local-stepfunctions provides the ability to retrieve these events through the eventLogs property that is part of the object returned by the StateMachine.run method. This feature is similar to the execution logs returned by the GetExecutionHistory action of the AWS Step Functions API.

Note that the eventLogs property is an AsyncGenerator, meaning that the events are yielded as they occur.

You could, for example, use these events to debug your state machine by having a better insight into how and when the execution transitions between the states of the machine.

An example usage of this feature can be found here.