asl

package
v1.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 24, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package asl implements an interpreter for the Amazon States Language (ASL) used by AWS Step Functions to define state machine workflows.

Index

Constants

View Source 
const StateTypeMap = "Map"

StateTypeMap is the ASL state type for Map states.

Variables

View Source 
var (
	ErrStateNotFound  = errors.New("state not found")
	ErrMaxTransitions = errors.New(
		"state machine exceeded maximum transitions",
	)
	ErrUnsupportedStateType             = errors.New("unsupported state type")
	ErrChoiceNoNext                     = errors.New("choice rule has no Next")
	ErrLambdaNotConfigured              = errors.New("lambda invoker not configured")
	ErrLambdaStatusError                = errors.New("lambda returned non-2xx status")
	ErrMapRequiresIterator              = errors.New("map state requires Iterator")
	ErrUnsupportedPathExpr              = errors.New("unsupported path expression")
	ErrUnsupportedResultPath            = errors.New("unsupported ResultPath")
	ErrCannotIndexNonObject             = errors.New("cannot index non-object with path")
	ErrFieldNotFound                    = errors.New("field not found")
	ErrMapInputNotArray                 = errors.New("input is not an array for Map state")
	ErrItemsPathNotArray                = errors.New("ItemsPath does not point to an array")
	ErrStatesTimeout                    = errors.New("States.Timeout")
	ErrSecondsPathNotNumber             = errors.New("SecondsPath did not resolve to a number")
	ErrTimestampPathNotString           = errors.New("TimestampPath did not resolve to a string")
	ErrNotAString                       = errors.New("not a string")
	ErrReferenceKeyNotString            = errors.New("value for reference key must be a string")
	ErrSQSIntegrationNotConfigured      = errors.New("SQS integration not configured")
	ErrSNSIntegrationNotConfigured      = errors.New("SNS integration not configured")
	ErrDynamoDBIntegrationNotConfigured = errors.New("DynamoDB integration not configured")
	ErrUnsupportedSQSAction             = errors.New("unsupported SQS action")
	ErrUnsupportedSNSAction             = errors.New("unsupported SNS action")
	ErrUnsupportedDynamoDBAction        = errors.New("unsupported DynamoDB action")
	ErrActivityNotConfigured            = errors.New("activity invoker not configured")
	ErrTaskTokenCallbackNotConfigured   = errors.New(
		"task token callback invoker not configured",
	)
	ErrECSIntegrationNotConfigured         = errors.New("ECS integration not configured")
	ErrGlueIntegrationNotConfigured        = errors.New("glue integration not configured")
	ErrEventBridgeIntegrationNotConfigured = errors.New("EventBridge integration not configured")
	ErrUnsupportedECSAction                = errors.New("unsupported ECS action")
	ErrUnsupportedGlueAction               = errors.New("unsupported Glue action")
	ErrUnsupportedEventBridgeAction        = errors.New("unsupported EventBridge action")
	ErrUnsupportedIntegration              = errors.New("unsupported service integration")
)

Sentinel errors for executor internals.

View Source 
var (
	ErrToleratedFailureCountNotNumber      = errors.New("ToleratedFailureCountPath: value is not a number")
	ErrToleratedFailurePercentageNotNumber = errors.New(
		"ToleratedFailurePercentagePath: value is not a number",
	)
)

Sentinel errors for Map state tolerated-failure threshold resolution.

View Source 
var (
	ErrInvalidIntrinsicSyntax               = errors.New("invalid intrinsic function syntax")
	ErrUnknownIntrinsicFunction             = errors.New("unknown intrinsic function")
	ErrInvalidIntrinsicArg                  = errors.New("invalid intrinsic function argument")
	ErrStatesFormatRequiresArg              = errors.New("States.Format requires at least one argument")
	ErrStatesFormatFirstArgNotString        = errors.New("States.Format: first argument must be a string")
	ErrStatesFormatNotEnoughArgs            = errors.New("States.Format: not enough arguments for placeholders")
	ErrStatesStringToJSONRequiresArg        = errors.New("States.StringToJson requires exactly one argument")
	ErrStatesStringToJSONArgNotString       = errors.New("States.StringToJson: argument must be a string")
	ErrStatesJSONToStringRequiresArg        = errors.New("States.JsonToString requires exactly one argument")
	ErrStatesArrayLengthRequiresArg         = errors.New("States.ArrayLength requires exactly one argument")
	ErrStatesArrayLengthArgNotArray         = errors.New("States.ArrayLength: argument must be an array")
	ErrStatesArrayContainsRequiresTwoArgs   = errors.New("States.ArrayContains requires exactly two arguments")
	ErrStatesArrayContainsFirstArgNotArray  = errors.New("States.ArrayContains: first argument must be an array")
	ErrStatesArrayPartitionRequiresTwoArgs  = errors.New("States.ArrayPartition requires exactly two arguments")
	ErrStatesArrayPartitionFirstArgNotArray = errors.New("States.ArrayPartition: first argument must be an array")
	ErrStatesArrayPartitionSizeNotPositive  = errors.New(
		"States.ArrayPartition: second argument must be a positive number",
	)
	ErrStatesMathRandomRequiresTwoArgs = errors.New("States.MathRandom requires at least two arguments (start, end)")
	ErrStatesMathRandomStartNotNumber  = errors.New("States.MathRandom: start must be a number")
	ErrStatesMathRandomEndNotNumber    = errors.New("States.MathRandom: end must be a number")
	ErrStatesMathRandomRange           = errors.New("States.MathRandom: end must be greater than start")
	ErrStatesBase64EncodeRequiresArg   = errors.New("States.Base64Encode requires exactly one argument")
	ErrStatesBase64EncodeArgNotString  = errors.New("States.Base64Encode: argument must be a string")
	ErrStatesBase64DecodeRequiresArg   = errors.New("States.Base64Decode requires exactly one argument")
	ErrStatesBase64DecodeArgNotString  = errors.New("States.Base64Decode: argument must be a string")
	ErrStatesHashRequiresTwoArgs       = errors.New("States.Hash requires exactly two arguments (data, algorithm)")
	ErrStatesHashFirstArgNotString     = errors.New("States.Hash: first argument must be a string")
	ErrStatesHashSecondArgNotString    = errors.New("States.Hash: second argument must be a string")
	ErrStatesHashUnsupportedAlgorithm  = errors.New("States.Hash: unsupported algorithm")
)

Sentinel errors for intrinsic function evaluation.

View Source 
var (
	ErrStatesUUIDNoArgs             = errors.New("States.UUID takes no arguments")
	ErrStatesMathAddRequiresTwoArgs = errors.New("States.MathAdd requires exactly two arguments")
	ErrStatesMathAddArgNotNumber    = errors.New("States.MathAdd: arguments must be numbers")
	ErrStatesArrayRangeRequiresArgs = errors.New(
		"States.ArrayRange requires exactly three arguments (start, end, step)",
	)
	ErrStatesArrayRangeArgNotNumber   = errors.New("States.ArrayRange: arguments must be numbers")
	ErrStatesArrayRangeStepZero       = errors.New("States.ArrayRange: step must be non-zero")
	ErrStatesArrayGetItemRequiresArgs = errors.New("States.ArrayGetItem requires exactly two arguments (array, index)")
	ErrStatesArrayGetItemNotArray     = errors.New("States.ArrayGetItem: first argument must be an array")
	ErrStatesArrayGetItemIndexRange   = errors.New("States.ArrayGetItem: index out of range")
	ErrStatesArrayUniqueRequiresArg   = errors.New("States.ArrayUnique requires exactly one argument")
	ErrStatesArrayUniqueArgNotArray   = errors.New("States.ArrayUnique: argument must be an array")
	ErrStatesJSONMergeRequiresArgs    = errors.New("States.JsonMerge requires exactly three arguments")
	ErrStatesJSONMergeArgNotObject    = errors.New("States.JsonMerge: first two arguments must be JSON objects")
	ErrStatesJSONMergeDeepUnsupported = errors.New(
		"States.JsonMerge: deep merge is not supported (third arg must be false)",
	)
	ErrStatesStringSplitRequiresArgs = errors.New("States.StringSplit requires exactly two arguments")
	ErrStatesStringSplitArgNotString = errors.New("States.StringSplit: arguments must be strings")
)

Sentinel errors for the extended intrinsic function set.

View Source 
var (
	ErrStatesStringConcatNoArgs       = errors.New("States.StringConcat requires at least one argument")
	ErrStatesStringConcatArgNotString = errors.New("States.StringConcat: arguments must be strings")
	ErrStatesArraySliceRequiresArgs   = errors.New("States.ArraySlice requires array, start, and end arguments")
	ErrStatesArraySliceNotArray       = errors.New("States.ArraySlice: first argument must be an array")
	ErrStatesArraySliceIndexNotNumber = errors.New("States.ArraySlice: start/end must be numbers")
	ErrStatesArrayFlattenRequiresArg  = errors.New("States.ArrayFlatten requires exactly one argument")
	ErrStatesArrayFlattenNotArray     = errors.New("States.ArrayFlatten: argument must be an array")
	ErrStatesArrayReverseRequiresArg  = errors.New("States.ArrayReverse requires exactly one argument")
	ErrStatesArrayReverseNotArray     = errors.New("States.ArrayReverse: argument must be an array")
	ErrStatesArraySortRequiresArg     = errors.New("States.ArraySort requires exactly one argument")
	ErrStatesArraySortNotArray        = errors.New("States.ArraySort: argument must be an array")
	ErrStatesArraySortMixedTypes      = errors.New("States.ArraySort: array must contain only numbers or only strings")
	ErrStatesMathSubRequiresTwoArgs   = errors.New("States.MathSubtract requires exactly two arguments")
	ErrStatesMathMulRequiresTwoArgs   = errors.New("States.MathMultiply requires exactly two arguments")
	ErrStatesMathDivRequiresTwoArgs   = errors.New("States.MathDivide requires exactly two arguments")
	ErrStatesMathModRequiresTwoArgs   = errors.New("States.MathMod requires exactly two arguments")
	ErrStatesMathMinRequiresTwoArgs   = errors.New("States.MathMin requires exactly two arguments")
	ErrStatesMathMaxRequiresTwoArgs   = errors.New("States.MathMax requires exactly two arguments")
	ErrStatesMathArgNotNumber         = errors.New("math intrinsic: arguments must be numbers")
	ErrStatesMathDivideByZero         = errors.New("States.MathDivide: division by zero")
	ErrStatesMathModByZero            = errors.New("States.MathMod: modulo by zero")
	ErrStatesStringLengthRequiresArg  = errors.New("States.StringLength requires exactly one argument")
	ErrStatesStringLengthArgNotString = errors.New("States.StringLength: argument must be a string")
	ErrStatesStringCaseRequiresArg    = errors.New("States.StringToLower/Upper require exactly one argument")
	ErrStatesStringCaseArgNotString   = errors.New("States.StringToLower/Upper: argument must be a string")
	ErrStatesStringIndexRequiresArgs  = errors.New("States.StringIndex requires exactly two arguments (string, substr)")
	ErrStatesStringIndexArgNotString  = errors.New("States.StringIndex: arguments must be strings")
)

Sentinel errors for the parity-extension intrinsic functions.

View Source 
var ErrChoiceNoMatch = errors.New("States.NoChoiceMatched")

ErrChoiceNoMatch is returned when a Choice state has no matching rule and no Default.

View Source 
var ErrExecutionFailed = errors.New("ExecutionFailed")

ErrExecutionFailed is returned when a Fail state is reached.

View Source 
var ErrHeartbeatSecondsPathNotNumber = errors.New("HeartbeatSecondsPath: value is not a number")

ErrHeartbeatSecondsPathNotNumber is returned when State.HeartbeatSecondsPath does not resolve to a number.

View Source 
var ErrItemReaderInvalidData = errors.New(
	"ItemReader: unable to parse S3 object as JSON array or JSON lines",
)

ErrItemReaderInvalidData is returned when ItemReader S3 object cannot be parsed as items.

View Source 
var ErrMaxConcurrencyPathNotNumber = errors.New("MaxConcurrencyPath: value is not a number")

ErrMaxConcurrencyPathNotNumber is returned when State.MaxConcurrencyPath does not resolve to a number.

View Source 
var ErrMaxInputBytesPerBatchPathNotNumber = errors.New(
	"MaxInputBytesPerBatchPath: value is not a number",
)

ErrMaxInputBytesPerBatchPathNotNumber is returned when ItemBatcher.MaxInputBytesPerBatchPath does not resolve to a number.

View Source 
var ErrMaxItemsPathNotNumber = errors.New("MaxItemsPath: value is not a number")

ErrMaxItemsPathNotNumber is returned when ReaderConfig.MaxItemsPath does not resolve to a number.

View Source 
var ErrMaxItemsPerBatchPathNotNumber = errors.New("MaxItemsPerBatchPath: value is not a number")

ErrMaxItemsPerBatchPathNotNumber is returned when ItemBatcher.MaxItemsPerBatchPath does not resolve to a number.

View Source 
var ErrParseError = errors.New("parse error")

ErrParseError is returned when the state machine definition cannot be parsed.

View Source 
var ErrS3ReaderNotConfigured = errors.New("S3 reader not configured for Map state ItemReader")

ErrS3ReaderNotConfigured is returned when ItemReader requires S3 but no S3Reader is set.

View Source 
var ErrTimeoutSecondsPathNotNumber = errors.New("TimeoutSecondsPath: value is not a number")

ErrTimeoutSecondsPathNotNumber is returned when State.TimeoutSecondsPath does not resolve to a number.

Functions

This section is empty.

Types

type ActivityInvoker 

type ActivityInvoker interface {
	// InvokeActivity enqueues a task and blocks until completed.
	// heartbeatSeconds > 0 enables heartbeat timeout enforcement.
	InvokeActivity(
		ctx context.Context,
		activityArn, input string,
		heartbeatSeconds int,
	) (string, error)
}

ActivityInvoker can enqueue an activity task and wait for its result.

type Branch 

type Branch struct {
	States  map[string]*State `json:"States"`
	StartAt string            `json:"StartAt"`
	Comment string            `json:"Comment,omitempty"`
}

Branch represents a parallel branch (or iterator root).

type Catcher 

type Catcher struct {
	Next        string   `json:"Next"`
	ResultPath  string   `json:"ResultPath,omitempty"`
	ErrorEquals []string `json:"ErrorEquals"`
}

Catcher defines catch behavior for a Task state on error.

type ChoiceRule 

type ChoiceRule struct {
	// Numeric comparisons
	NumericEquals                *float64 `json:"NumericEquals,omitempty"`
	NumericLessThan              *float64 `json:"NumericLessThan,omitempty"`
	NumericGreaterThan           *float64 `json:"NumericGreaterThan,omitempty"`
	NumericLessThanEquals        *float64 `json:"NumericLessThanEquals,omitempty"`
	NumericGreaterThanEquals     *float64 `json:"NumericGreaterThanEquals,omitempty"`
	NumericEqualsPath            *string  `json:"NumericEqualsPath,omitempty"`
	NumericLessThanPath          *string  `json:"NumericLessThanPath,omitempty"`
	NumericGreaterThanPath       *string  `json:"NumericGreaterThanPath,omitempty"`
	NumericLessThanEqualsPath    *string  `json:"NumericLessThanEqualsPath,omitempty"`
	NumericGreaterThanEqualsPath *string  `json:"NumericGreaterThanEqualsPath,omitempty"`

	// String comparisons
	StringEquals                *string `json:"StringEquals,omitempty"`
	StringLessThan              *string `json:"StringLessThan,omitempty"`
	StringGreaterThan           *string `json:"StringGreaterThan,omitempty"`
	StringLessThanEquals        *string `json:"StringLessThanEquals,omitempty"`
	StringGreaterThanEquals     *string `json:"StringGreaterThanEquals,omitempty"`
	StringEqualsPath            *string `json:"StringEqualsPath,omitempty"`
	StringLessThanPath          *string `json:"StringLessThanPath,omitempty"`
	StringGreaterThanPath       *string `json:"StringGreaterThanPath,omitempty"`
	StringLessThanEqualsPath    *string `json:"StringLessThanEqualsPath,omitempty"`
	StringGreaterThanEqualsPath *string `json:"StringGreaterThanEqualsPath,omitempty"`
	StringMatches               *string `json:"StringMatches,omitempty"`

	// Timestamp comparisons (ISO 8601 / RFC3339 strings)
	TimestampEquals                *string `json:"TimestampEquals,omitempty"`
	TimestampLessThan              *string `json:"TimestampLessThan,omitempty"`
	TimestampGreaterThan           *string `json:"TimestampGreaterThan,omitempty"`
	TimestampLessThanEquals        *string `json:"TimestampLessThanEquals,omitempty"`
	TimestampGreaterThanEquals     *string `json:"TimestampGreaterThanEquals,omitempty"`
	TimestampEqualsPath            *string `json:"TimestampEqualsPath,omitempty"`
	TimestampLessThanPath          *string `json:"TimestampLessThanPath,omitempty"`
	TimestampGreaterThanPath       *string `json:"TimestampGreaterThanPath,omitempty"`
	TimestampLessThanEqualsPath    *string `json:"TimestampLessThanEqualsPath,omitempty"`
	TimestampGreaterThanEqualsPath *string `json:"TimestampGreaterThanEqualsPath,omitempty"`

	// Boolean comparison
	BooleanEquals     *bool   `json:"BooleanEquals,omitempty"`
	BooleanEqualsPath *string `json:"BooleanEqualsPath,omitempty"`

	// Existence and type checks
	IsNull      *bool `json:"IsNull,omitempty"`
	IsPresent   *bool `json:"IsPresent,omitempty"`
	IsString    *bool `json:"IsString,omitempty"`
	IsNumeric   *bool `json:"IsNumeric,omitempty"`
	IsBoolean   *bool `json:"IsBoolean,omitempty"`
	IsTimestamp *bool `json:"IsTimestamp,omitempty"`

	// Logical operators
	Not      *ChoiceRule  `json:"Not,omitempty"`
	Variable string       `json:"Variable,omitempty"`
	Next     string       `json:"Next,omitempty"`
	And      []ChoiceRule `json:"And,omitempty"`
	Or       []ChoiceRule `json:"Or,omitempty"`
}

ChoiceRule represents a single condition/transition in a Choice state.

type DynamoDBIntegration 

type DynamoDBIntegration interface {
	SFNPutItem(ctx context.Context, input any) (any, error)
	SFNGetItem(ctx context.Context, input any) (any, error)
	SFNDeleteItem(ctx context.Context, input any) (any, error)
	SFNUpdateItem(ctx context.Context, input any) (any, error)
	SFNBatchExecuteStatement(ctx context.Context, input any) (any, error)
	SFNBatchGetItem(ctx context.Context, input any) (any, error)
	SFNBatchWriteItem(ctx context.Context, input any) (any, error)
	SFNCreateBackup(ctx context.Context, input any) (any, error)
	SFNCreateGlobalTable(ctx context.Context, input any) (any, error)
	SFNCreateTable(ctx context.Context, input any) (any, error)
	SFNDeleteBackup(ctx context.Context, input any) (any, error)
	SFNDeleteResourcePolicy(ctx context.Context, input any) (any, error)
	SFNDeleteTable(ctx context.Context, input any) (any, error)
}

DynamoDBIntegration handles Step Functions DynamoDB service integration.

type ECSIntegration 

type ECSIntegration interface {
	// SFNRunTask runs an ECS task and returns the response map (Tasks, Failures).
	SFNRunTask(ctx context.Context, input map[string]any) (any, error)
}

ECSIntegration handles Step Functions ECS service integration.

type EventBridgeIntegration 

type EventBridgeIntegration interface {
	// SFNPutEvents puts events to an EventBridge bus and returns failed-entry count.
	SFNPutEvents(ctx context.Context, entries []map[string]any) (int, error)
}

EventBridgeIntegration handles Step Functions EventBridge service integration.

type ExecutionResult 

type ExecutionResult struct {
	Output any
	Error  string
	Cause  string
	// Failed is true iff a Fail state (or an unhandled Task failure) ended
	// the execution. A Fail state's Error/Cause are both optional per the
	// ASL spec, so Error alone cannot distinguish "failed with no error
	// code" from "succeeded" -- callers must check Failed, not Error != "".
	Failed bool
}

ExecutionResult holds the final output and status of a state machine execution.

type Executor 

type Executor struct {
	// contains filtered or unexported fields
}

Executor runs an ASL state machine.

func NewExecutor 

func NewExecutor(sm *StateMachine, lambda LambdaInvoker, history HistoryRecorder) *Executor

NewExecutor creates an Executor for the given state machine.

func (*Executor) Execute 

func (e *Executor) Execute(
	ctx context.Context,
	executionARN, inputJSON string,
) (*ExecutionResult, error)

Execute runs the state machine with the given input JSON and returns the result.

func (*Executor) SetActivityInvoker 

func (e *Executor) SetActivityInvoker(ai ActivityInvoker)

SetActivityInvoker configures the activity invoker for activity Task states.

func (*Executor) SetDynamoDBIntegration 

func (e *Executor) SetDynamoDBIntegration(ddb DynamoDBIntegration)

SetDynamoDBIntegration configures the DynamoDB integration for Task states.

func (*Executor) SetECSIntegration 

func (e *Executor) SetECSIntegration(ecs ECSIntegration)

SetECSIntegration configures the ECS integration for Task states.

func (*Executor) SetEventBridgeIntegration 

func (e *Executor) SetEventBridgeIntegration(eb EventBridgeIntegration)

SetEventBridgeIntegration configures the EventBridge integration for Task states.

func (*Executor) SetExecutionContext 

func (e *Executor) SetExecutionContext(
	executionARN, executionName, roleArn, startTime, stateMachineARN, stateMachineName string,
)

SetExecutionContext sets the metadata that will be exposed via `$$.Execution.*` and `$$.StateMachine.*` JSONPath references during evaluation.

func (*Executor) SetGlueIntegration 

func (e *Executor) SetGlueIntegration(glue GlueIntegration)

SetGlueIntegration configures the Glue integration for Task states.

func (*Executor) SetMapRunNotifier 

func (e *Executor) SetMapRunNotifier(n MapRunNotifier)

SetMapRunNotifier configures the MapRun notifier for Map states.

func (*Executor) SetS3Reader 

func (e *Executor) SetS3Reader(s3 S3Reader)

SetS3Reader configures the S3 reader for Map state ItemReader.

func (*Executor) SetS3ResultWriter added in v1.3.1 

func (e *Executor) SetS3ResultWriter(w S3Writer)

SetS3ResultWriter configures the S3 writer for Distributed Map ResultWriter.

func (*Executor) SetSNSIntegration 

func (e *Executor) SetSNSIntegration(sns SNSIntegration)

SetSNSIntegration configures the SNS integration for Task states.

func (*Executor) SetSQSIntegration 

func (e *Executor) SetSQSIntegration(sqs SQSIntegration)

SetSQSIntegration configures the SQS integration for Task states.

func (*Executor) SetTaskTokenCallbackInvoker 

func (e *Executor) SetTaskTokenCallbackInvoker(invoker TaskTokenCallbackInvoker)

SetTaskTokenCallbackInvoker configures callback waiting for .waitForTaskToken integrations.

type FailError 

type FailError struct {
	ErrCode string
	Cause   string
}

FailError represents the error from a Fail state.

func (*FailError) Error 

func (e *FailError) Error() string

type GlueIntegration 

type GlueIntegration interface {
	// SFNStartJobRun starts a Glue job run and returns the JobRunId.
	SFNStartJobRun(ctx context.Context, jobName string, arguments map[string]string) (string, error)
}

GlueIntegration handles Step Functions Glue service integration.

type HistoryRecorder 

type HistoryRecorder interface {
	RecordStateEntered(executionARN, stateName, stateType string, input any)
	RecordStateExited(executionARN, stateName, stateType string, output any)
	RecordTaskScheduled(executionARN, stateName, resource string, parameters any)
	RecordTaskSucceeded(executionARN, stateName, resource string, output any)
	RecordTaskFailed(executionARN, stateName, resource, errCode, cause string)
}

HistoryRecorder is called during execution to record state transition events.

type ItemBatcher 

type ItemBatcher struct {
	MaxItemsPerBatchPath      string `json:"MaxItemsPerBatchPath,omitempty"`
	MaxInputBytesPerBatchPath string `json:"MaxInputBytesPerBatchPath,omitempty"`
	// BatchInput is fixed JSON merged into every batch's iteration input
	// alongside Items (AWS docs: input-output-itembatcher.html, "Batch input").
	BatchInput json.RawMessage `json:"BatchInput,omitempty"`
	// MaxItemsPerBatch is the maximum number of items per batch. Zero means no limit.
	MaxItemsPerBatch int `json:"MaxItemsPerBatch,omitempty"`
	// MaxInputBytesPerBatch is the max total JSON bytes per batch. Zero means no limit.
	MaxInputBytesPerBatch int `json:"MaxInputBytesPerBatch,omitempty"`
}

ItemBatcher configures batching for a Map state's Distributed Map. MaxItemsPerBatch/MaxInputBytesPerBatch are mutually exclusive with their *Path siblings, which are reference paths resolved against the Map state's pre-Parameters input -- same resolution as ToleratedFailureCountPath (AWS docs: input-output-itembatcher.html).

type ItemReader 

type ItemReader struct {
	Parameters   map[string]any `json:"Parameters,omitempty"`
	ReaderConfig *ReaderConfig  `json:"ReaderConfig,omitempty"`
	Resource     string         `json:"Resource,omitempty"`
}

ItemReader configures reading items from S3 for a Map state's Distributed Map.

type LambdaInvoker 

type LambdaInvoker interface {
	InvokeFunction(
		ctx context.Context,
		name, invocationType string,
		payload []byte,
	) ([]byte, int, error)
}

LambdaInvoker can invoke a Lambda function.

type MapRunNotifier 

type MapRunNotifier interface {
	OnMapRunStart(executionARN, stateName string, maxConcurrency, itemCount int) string
	// resultsWritten is the count of items whose result was actually written
	// by a ResultWriter (0 when ResultWriter isn't configured), matching
	// DescribeMapRun's ItemCounts.ResultsWritten semantics.
	OnMapRunEnd(mapRunARN, status string, succeeded, failed, total, resultsWritten int)
}

MapRunNotifier receives callbacks when Map state runs start and end. Implement this to track Map state execution in a backend.

type ProcessorConfig added in v1.3.4 

type ProcessorConfig struct {
	Mode          string `json:"Mode,omitempty"`
	ExecutionType string `json:"ExecutionType,omitempty"`
}

ProcessorConfig specifies configuration for an ItemProcessor.

type ReaderConfig 

type ReaderConfig struct {
	InputType         string   `json:"InputType,omitempty"`
	CSVHeaderLocation string   `json:"CSVHeaderLocation,omitempty"`
	MaxItemsPath      string   `json:"MaxItemsPath,omitempty"`
	CSVHeaders        []string `json:"CSVHeaders,omitempty"`
	MaxItems          int      `json:"MaxItems,omitempty"`
}

ReaderConfig describes how the ItemReader should interpret S3 object data. InputType: "JSON" (default), "JSONL", or "CSV". CSVHeaderLocation: "FIRST_ROW" or "GIVEN". CSVHeaders: explicit headers when CSVHeaderLocation == "GIVEN". MaxItems: optional cap on number of items returned (0 = unlimited). MaxItemsPath is MaxItems' reference-path sibling, mutually exclusive with it and resolved against the Map state's pre-Parameters input (AWS docs: input-output-itemreader.html).

type ResultWriter added in v1.3.1 

type ResultWriter struct {
	Parameters   map[string]any      `json:"Parameters,omitempty"`
	WriterConfig *ResultWriterConfig `json:"WriterConfig,omitempty"`
	Resource     string              `json:"Resource,omitempty"`
}

ResultWriter configures exporting a Distributed Map state's per-item results to S3 instead of returning them inline as the state's output (AWS docs: input-output-resultwriter.html). Only the Resource+Parameters (S3 export) combination is applied; WriterConfig is parsed but not honored -- see Executor.exportMapResults.

type ResultWriterConfig added in v1.3.1 

type ResultWriterConfig struct {
	Transformation string `json:"Transformation,omitempty"`
	OutputType     string `json:"OutputType,omitempty"`
}

ResultWriterConfig is ResultWriter.WriterConfig: Transformation ("NONE"|"COMPACT"|"FLATTEN") and OutputType ("JSON"|"JSONL"). Parsed for forward compatibility but not currently applied.

type ResultWriterDetails added in v1.3.1 

type ResultWriterDetails struct {
	Bucket string `json:"Bucket"`
	Key    string `json:"Key"`
}

ResultWriterDetails points to a Distributed Map's exported result manifest.

type Retrier 

type Retrier struct {
	IntervalSeconds *int     `json:"IntervalSeconds,omitempty"`
	MaxAttempts     *int     `json:"MaxAttempts,omitempty"`
	MaxDelaySeconds *int     `json:"MaxDelaySeconds,omitempty"`
	JitterStrategy  string   `json:"JitterStrategy,omitempty"`
	ErrorEquals     []string `json:"ErrorEquals"`
	BackoffRate     float64  `json:"BackoffRate,omitempty"`
}

Retrier defines retry behavior for a Task state on error.

JitterStrategy controls whether the computed backoff delay is randomized: "FULL" randomizes the delay uniformly between 0 and the computed value; "NONE" (the AWS default when omitted) uses the computed delay as-is. MaxDelaySeconds, when set, caps the delay between retry attempts.

type S3Reader 

type S3Reader interface {
	// GetObjectBytes returns the raw bytes of an S3 object by bucket and key.
	GetObjectBytes(ctx context.Context, bucket, key string) ([]byte, error)
}

S3Reader reads objects from S3 for Map state ItemReader.

type S3Writer added in v1.3.1 

type S3Writer interface {
	PutObjectBytes(ctx context.Context, bucket, key string, data []byte) error
}

S3Writer writes objects to S3 for a Distributed Map state's ResultWriter.

type SNSIntegration 

type SNSIntegration interface {
	SFNPublish(ctx context.Context, topicARN, message, subject string) (messageID string, err error)
}

SNSIntegration handles Step Functions SNS service integration.

type SQSIntegration 

type SQSIntegration interface {
	SFNSendMessage(
		ctx context.Context,
		queueURL, messageBody, groupID, deduplicationID string,
		delaySeconds int,
	) (messageID string, md5 string, err error)
}

SQSIntegration handles Step Functions SQS service integration.

type State 

type State struct {
	Iterator      *StateMachine   `json:"Iterator,omitempty"`
	ItemProcessor *StateMachine   `json:"ItemProcessor,omitempty"`
	ItemBatcher   *ItemBatcher    `json:"ItemBatcher,omitempty"`
	ItemReader    *ItemReader     `json:"ItemReader,omitempty"`
	ResultWriter  *ResultWriter   `json:"ResultWriter,omitempty"`
	ItemSelector  json.RawMessage `json:"ItemSelector,omitempty"`
	SecondsPath   string          `json:"SecondsPath,omitempty"`
	TimestampPath string          `json:"TimestampPath,omitempty"`
	ItemsPath     string          `json:"ItemsPath,omitempty"`
	// ToleratedFailureCount/Percentage (and their *Path variants) bound how many
	// Map iterations may fail before the Map state itself fails with
	// States.ExceedToleratedFailureThreshold. AWS supports these only for
	// Distributed Map, but the emulator applies them uniformly since Map
	// processing mode is not otherwise distinguished. When both a count and a
	// percentage are set, the Map fails when EITHER threshold is crossed.
	ToleratedFailureCountPath      string   `json:"ToleratedFailureCountPath,omitempty"`
	ToleratedFailurePercentagePath string   `json:"ToleratedFailurePercentagePath,omitempty"`
	ToleratedFailureCount          *int     `json:"ToleratedFailureCount,omitempty"`
	ToleratedFailurePercentage     *float64 `json:"ToleratedFailurePercentage,omitempty"`
	// MaxConcurrencyPath is MaxConcurrency's reference-path sibling, resolved
	// against the Map state's pre-Parameters input the same way as
	// ToleratedFailureCountPath (AWS docs:
	// state-map-distributed.html#map-state-distributed-additional-fields).
	MaxConcurrencyPath string `json:"MaxConcurrencyPath,omitempty"`
	InputPath          string `json:"InputPath,omitempty"`
	OutputPath         string `json:"OutputPath,omitempty"`
	ResultPath         string `json:"ResultPath,omitempty"`
	Type               string `json:"Type"`
	Error              string `json:"Error,omitempty"`
	Cause              string `json:"Cause,omitempty"`
	Comment            string `json:"Comment,omitempty"`
	Next               string `json:"Next,omitempty"`
	Default            string `json:"Default,omitempty"`
	Timestamp          string `json:"Timestamp,omitempty"`
	Resource           string `json:"Resource,omitempty"`
	// TimeoutSecondsPath/HeartbeatSecondsPath are TimeoutSeconds/HeartbeatSeconds's
	// reference-path siblings, mutually exclusive with them and resolved against
	// the Task state's pre-Parameters input (AWS docs:
	// amazon-states-language-task-state.html, GlueJobTask example).
	TimeoutSecondsPath   string          `json:"TimeoutSecondsPath,omitempty"`
	HeartbeatSecondsPath string          `json:"HeartbeatSecondsPath,omitempty"`
	Retry                []Retrier       `json:"Retry,omitempty"`
	Catch                []Catcher       `json:"Catch,omitempty"`
	Choices              []ChoiceRule    `json:"Choices,omitempty"`
	Result               json.RawMessage `json:"Result,omitempty"`
	Branches             []Branch        `json:"Branches,omitempty"`
	Parameters           json.RawMessage `json:"Parameters,omitempty"`
	ResultSelector       json.RawMessage `json:"ResultSelector,omitempty"`
	TimeoutSeconds       int             `json:"TimeoutSeconds,omitempty"`
	HeartbeatSeconds     int             `json:"HeartbeatSeconds,omitempty"`
	Seconds              int             `json:"Seconds,omitempty"`
	MaxConcurrency       int             `json:"MaxConcurrency,omitempty"`
	End                  bool            `json:"End,omitempty"`
}

State represents a single state in the state machine.

type StateMachine 

type StateMachine struct {
	ProcessorConfig *ProcessorConfig  `json:"ProcessorConfig,omitempty"`
	States          map[string]*State `json:"States"`
	Comment         string            `json:"Comment,omitempty"`
	StartAt         string            `json:"StartAt"`
}

StateMachine represents a parsed ASL state machine definition.

func Parse 

func Parse(definition string) (*StateMachine, error)

Parse parses an ASL state machine definition from JSON.

type TaskTokenCallbackInvoker 

type TaskTokenCallbackInvoker interface {
	WaitForTaskToken(ctx context.Context, taskToken string, heartbeatSeconds int) (string, error)
}

TaskTokenCallbackInvoker waits for SendTaskSuccess/SendTaskFailure callbacks for a task token.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.