Skip to content

Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.

feat: support nested Step Functions startExecution.sync tasks (#157)

Jay Janssena15917c33db9
diff --git a/ministack/services/stepfunctions.py b/ministack/services/stepfunctions.py
index 5abc2c6b..67590a42 100644
--- a/ministack/services/stepfunctions.py
+++ b/ministack/services/stepfunctions.py
@@ -1200,6 +1200,9 @@ def _invoke_resource(resource, input_data):
if ":activity:" in resource:
return _invoke_activity(resource, input_data)
+ if resource.startswith("arn:aws:states:::states:startExecution.sync"):
+ return _invoke_nested_start_execution(resource, input_data)
+
# Service integration dispatch
clean = resource.replace(".sync", "").replace(".waitForTaskToken", "")
for prefix, handler in _SERVICE_DISPATCH.items():
@@ -1770,6 +1773,79 @@ def _parse_ts(v):
# ===================================================================
+def _invoke_nested_start_execution(resource, input_data):
+ """Run a nested Step Functions execution and wait for the child result."""
+ request = _nested_start_execution_request(input_data)
+ status, _, body = _start_sync_execution(request)
+ payload = json.loads(body) if body else {}
+
+ if status >= 400:
+ raise _ExecutionError(
+ payload.get("__type", "States.Runtime"),
+ payload.get("message", "Nested execution failed to start"),
+ )
+
+ if payload.get("status") != "SUCCEEDED":
+ error, cause = _nested_execution_failure(payload)
+ raise _ExecutionError(error, cause)
+
+ output_value = payload.get("output") or "{}"
+ if resource.endswith(".sync:2") and isinstance(output_value, str):
+ try:
+ output_value = json.loads(output_value)
+ except json.JSONDecodeError:
+ pass
+
+ return {
+ "ExecutionArn": payload.get("executionArn"),
+ "Input": payload.get("input", "{}"),
+ "InputDetails": payload.get("inputDetails", {"included": True}),
+ "Name": payload.get("name"),
+ "Output": output_value,
+ "OutputDetails": payload.get("outputDetails", {"included": True}),
+ "StartDate": payload.get("startDate"),
+ "StateMachineArn": payload.get("stateMachineArn"),
+ "Status": payload.get("status"),
+ "StopDate": payload.get("stopDate"),
+ }
+
+
+def _nested_start_execution_request(input_data):
+ state_machine_arn = input_data.get("StateMachineArn") or input_data.get("stateMachineArn")
+ if not state_machine_arn:
+ raise _ExecutionError("ValidationException", "StateMachineArn is required")
+
+ nested_input = input_data.get("Input", input_data.get("input", {}))
+ if isinstance(nested_input, str):
+ input_str = nested_input
+ else:
+ input_str = json.dumps(nested_input)
+
+ request = {
+ "stateMachineArn": state_machine_arn,
+ "input": input_str,
+ }
+ name = input_data.get("Name") or input_data.get("name")
+ if name:
+ request["name"] = name
+ return request
+
+
+def _nested_execution_failure(payload):
+ output = payload.get("output")
+ if isinstance(output, str):
+ try:
+ decoded = json.loads(output)
+ except json.JSONDecodeError:
+ decoded = None
+ if isinstance(decoded, dict) and decoded.get("Error"):
+ return decoded["Error"], decoded.get("Cause", "")
+
+ execution_arn = payload.get("executionArn", "")
+ status = payload.get("status", "FAILED")
+ return "States.TaskFailed", f"Nested execution {execution_arn} ended with status {status}"
+
+
def _invoke_sqs_send_message(resource, input_data):
"""arn:aws:states:::sqs:sendMessage"""
try:
diff --git a/tests/test_services.py b/tests/test_services.py
index 913eca99..39b82b44 100644
--- a/tests/test_services.py
+++ b/tests/test_services.py
@@ -7730,6 +7730,158 @@ def test_sfn_integration_ecs_run_task_output_contains_status(sfn, ecs):
assert "failures" in output
+def test_sfn_integration_nested_start_execution_sync_returns_string_output(sfn):
+ """states:startExecution.sync should return the child Output as a JSON string."""
+ unique = str(time.time_ns())
+
+ child_definition = json.dumps(
+ {
+ "StartAt": "BuildResult",
+ "States": {
+ "BuildResult": {
+ "Type": "Pass",
+ "Result": {"message": "child-ok", "version": 1},
+ "End": True,
+ }
+ },
+ }
+ )
+ child = sfn.create_state_machine(
+ name=f"sfn-child-sync-{unique}",
+ definition=child_definition,
+ roleArn="arn:aws:iam::000000000000:role/R",
+ )
+
+ parent_definition = json.dumps(
+ {
+ "StartAt": "RunChild",
+ "States": {
+ "RunChild": {
+ "Type": "Task",
+ "Resource": "arn:aws:states:::states:startExecution.sync",
+ "Parameters": {
+ "StateMachineArn": child["stateMachineArn"],
+ "Input": {"requestId.$": "$.requestId"},
+ },
+ "End": True,
+ }
+ },
+ }
+ )
+ parent = sfn.create_state_machine(
+ name=f"sfn-parent-sync-{unique}",
+ definition=parent_definition,
+ roleArn="arn:aws:iam::000000000000:role/R",
+ )
+
+ ex = sfn.start_execution(
+ stateMachineArn=parent["stateMachineArn"],
+ input=json.dumps({"requestId": "req-123"}),
+ )
+
+ desc = _wait_sfn(sfn, ex["executionArn"])
+ assert desc["status"] == "SUCCEEDED"
+
+ output = json.loads(desc["output"])
+ assert output["Status"] == "SUCCEEDED"
+ assert isinstance(output["Output"], str)
+ assert json.loads(output["Output"]) == {"message": "child-ok", "version": 1}
+
+ child_execs = sfn.list_executions(
+ stateMachineArn=child["stateMachineArn"],
+ statusFilter="SUCCEEDED",
+ )["executions"]
+ assert any(e["executionArn"] == output["ExecutionArn"] for e in child_execs)
+
+
+def test_sfn_integration_nested_start_execution_sync2_returns_json_output(sfn):
+ """states:startExecution.sync:2 should expose the child Output as JSON."""
+ unique = str(time.time_ns())
+
+ child_definition = json.dumps(
+ {
+ "StartAt": "Echo",
+ "States": {
+ "Echo": {
+ "Type": "Pass",
+ "Parameters": {
+ "childValue.$": "$.value",
+ "source": "child",
+ },
+ "End": True,
+ }
+ },
+ }
+ )
+ child = sfn.create_state_machine(
+ name=f"sfn-child-sync2-{unique}",
+ definition=child_definition,
+ roleArn="arn:aws:iam::000000000000:role/R",
+ )
+
+ parent_definition = json.dumps(
+ {
+ "StartAt": "RunChild",
+ "States": {
+ "RunChild": {
+ "Type": "Task",
+ "Resource": "arn:aws:states:::states:startExecution.sync:2",
+ "Parameters": {
+ "StateMachineArn": child["stateMachineArn"],
+ "Input": {"value.$": "$.value"},
+ },
+ "ResultPath": "$.child",
+ "Next": "CheckChild",
+ },
+ "CheckChild": {
+ "Type": "Choice",
+ "Choices": [
+ {
+ "Variable": "$.child.Output.childValue",
+ "StringEquals": "expected",
+ "Next": "Done",
+ }
+ ],
+ "Default": "WrongChildOutput",
+ },
+ "WrongChildOutput": {
+ "Type": "Fail",
+ "Error": "WrongChildOutput",
+ },
+ "Done": {
+ "Type": "Succeed",
+ },
+ },
+ }
+ )
+ parent = sfn.create_state_machine(
+ name=f"sfn-parent-sync2-{unique}",
+ definition=parent_definition,
+ roleArn="arn:aws:iam::000000000000:role/R",
+ )
+
+ ex = sfn.start_execution(
+ stateMachineArn=parent["stateMachineArn"],
+ input=json.dumps({"value": "expected"}),
+ )
+
+ desc = _wait_sfn(sfn, ex["executionArn"])
+ assert desc["status"] == "SUCCEEDED"
+
+ output = json.loads(desc["output"])
+ assert output["child"]["Status"] == "SUCCEEDED"
+ assert output["child"]["Output"] == {
+ "childValue": "expected",
+ "source": "child",
+ }
+
+ child_execs = sfn.list_executions(
+ stateMachineArn=child["stateMachineArn"],
+ statusFilter="SUCCEEDED",
+ )["executions"]
+ assert any(e["executionArn"] == output["child"]["ExecutionArn"] for e in child_execs)
+
+
def test_sfn_integration_multi_service_pipeline(sfn, sqs, ddb):
"""End-to-end: Pass → DynamoDB putItem → SQS sendMessage → Succeed."""
table_name = "sfn-pipeline-test"