Skip to content

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

feat: add query-protocol aws-sdk:* task dispatcher for Step Functions (#174)

Jay Janssen103316fa4d57
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 54fad473..cbf7ffa9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,11 +9,13 @@ Versioning follows [Semantic Versioning](https://semver.org/).
## [Unreleased]
+### Added
+- **Step Functions query-protocol `aws-sdk:*` task dispatcher** — Task states can now call query-protocol AWS services (RDS, SQS, SNS, ElastiCache, EC2, IAM, STS, CloudWatch) via `arn:aws:states:::aws-sdk:<service>:<action>` resource ARNs. Converts JSON parameters to query-encoded form data and parses XML responses back to JSON. Contributed by @jayjanssen
+
### Tests
-- 5 new tests: comprehensive `aws-sdk:secretsmanager` Step Functions task dispatch coverage — PutSecretValue+GetSecretValue round-trip, GetRandomPassword, DeleteSecret, full create→put→get→describe→delete lifecycle, and error propagation for missing secrets. Contributed by @jayjanssen
+- 4 new tests: `aws-sdk:rds` Step Functions task dispatch — CreateDBCluster+DescribeDBClusters, CreateDBInstance+DescribeDBInstances, ModifyDBCluster, and error propagation for missing clusters. Contributed by @jayjanssen
---
-
## [1.1.47] — 2026-04-07
### Added
diff --git a/ministack/services/stepfunctions.py b/ministack/services/stepfunctions.py
index 3e94467c..af09de45 100644
--- a/ministack/services/stepfunctions.py
+++ b/ministack/services/stepfunctions.py
@@ -2120,7 +2120,7 @@ _AWS_SDK_SERVICE_MAP = {
"ecs": {"target_prefix": "AmazonEC2ContainerServiceV20141113", "protocol": "json"},
"ecr": {"target_prefix": "AmazonEC2ContainerRegistry_V20150921", "protocol": "json"},
"kms": {"target_prefix": "TrentService", "protocol": "json"},
- # Query-protocol services (not yet supported via aws-sdk dispatcher)
+ # Query-protocol services
"sqs": {"protocol": "query"},
"sns": {"protocol": "query"},
"rds": {"protocol": "query"},
@@ -2191,6 +2191,142 @@ def _dispatch_aws_sdk_json(service_info, service_name, action, input_data):
return result
+def _flatten_query_params(data, prefix=""):
+ """Flatten a JSON dict into AWS query-protocol form params.
+
+ Handles nested dicts, lists (Member.N convention), and scalar values.
+ """
+ params = {}
+ if not isinstance(data, dict):
+ return params
+ for key, value in data.items():
+ full_key = f"{prefix}{key}" if not prefix else f"{prefix}.{key}"
+ if isinstance(value, dict):
+ params.update(_flatten_query_params(value, full_key))
+ elif isinstance(value, list):
+ for i, item in enumerate(value, 1):
+ member_key = f"{full_key}.member.{i}"
+ if isinstance(item, dict):
+ params.update(_flatten_query_params(item, member_key))
+ else:
+ params[member_key] = str(item)
+ elif isinstance(value, bool):
+ params[full_key] = "true" if value else "false"
+ else:
+ params[full_key] = str(value)
+ return params
+
+
+def _xml_element_to_dict(element):
+ """Convert an XML element tree to a JSON-friendly dict.
+
+ Strips namespace prefixes. Repeated child tags become lists.
+ Leaf text nodes become strings.
+ """
+ # Strip namespace
+ tag = element.tag.split("}")[-1] if "}" in element.tag else element.tag
+
+ children = list(element)
+ if not children:
+ # Leaf node
+ return tag, (element.text or "")
+
+ result = {}
+ for child in children:
+ child_tag, child_val = _xml_element_to_dict(child)
+ if child_tag in result:
+ existing = result[child_tag]
+ if not isinstance(existing, list):
+ result[child_tag] = [existing]
+ result[child_tag].append(child_val)
+ else:
+ result[child_tag] = child_val
+ return tag, result
+
+
+def _dispatch_aws_sdk_query(service_info, service_name, action, input_data):
+ """Dispatch an aws-sdk integration call to a query-protocol MiniStack service."""
+ import xml.etree.ElementTree as ET
+ from urllib.parse import urlencode
+ from ministack import app
+
+ service_key = service_info.get("service_key", service_name)
+ handler = app.SERVICE_HANDLERS.get(service_key)
+ if not handler:
+ raise _ExecutionError(
+ "States.Runtime",
+ f"Service '{service_key}' is not available in MiniStack",
+ )
+
+ # Build form-encoded body with Action param
+ form_params = {"Action": action}
+ form_params.update(_flatten_query_params(input_data))
+ body = urlencode(form_params)
+
+ headers = {
+ "content-type": "application/x-www-form-urlencoded",
+ "host": f"{service_key}.{REGION}.amazonaws.com",
+ "authorization": (
+ f"AWS4-HMAC-SHA256 Credential=test/20260101/{REGION}/{service_key}/aws4_request"
+ ),
+ }
+
+ coro = handler("POST", "/", headers, body, {})
+ try:
+ coro.send(None)
+ except StopIteration as stop:
+ status, resp_headers, resp_body = stop.value
+ else:
+ coro.close()
+ loop = asyncio.new_event_loop()
+ try:
+ status, resp_headers, resp_body = loop.run_until_complete(
+ handler("POST", "/", headers, body, {})
+ )
+ finally:
+ loop.close()
+
+ decoded = resp_body.decode("utf-8") if isinstance(resp_body, bytes) else resp_body
+
+ # Parse XML response to JSON
+ if status >= 400:
+ # Try to extract error from XML
+ try:
+ root = ET.fromstring(decoded)
+ err_el = root.find(".//{http://rds.amazonaws.com/doc/2014-10-31/}Error")
+ if err_el is None:
+ # Try without namespace
+ err_el = root.find(".//Error")
+ if err_el is not None:
+ code = err_el.findtext("{http://rds.amazonaws.com/doc/2014-10-31/}Code")
+ if code is None:
+ code = err_el.findtext("Code")
+ msg = err_el.findtext("{http://rds.amazonaws.com/doc/2014-10-31/}Message")
+ if msg is None:
+ msg = err_el.findtext("Message")
+ raise _ExecutionError(code or f"{service_name}.ServiceException", msg or decoded)
+ except _ExecutionError:
+ raise
+ except Exception:
+ pass
+ raise _ExecutionError(f"{service_name}.ServiceException", decoded)
+
+ # Convert successful XML response to dict
+ try:
+ root = ET.fromstring(decoded)
+ _, result = _xml_element_to_dict(root)
+ if isinstance(result, dict):
+ # Unwrap the <ActionResult> wrapper if present
+ result_key = f"{action}Result"
+ if result_key in result:
+ result = result[result_key]
+ # Drop ResponseMetadata
+ result.pop("ResponseMetadata", None)
+ return result
+ except ET.ParseError:
+ raise _ExecutionError("States.Runtime", f"Failed to parse {service_name} XML response")
+
+
def _invoke_aws_sdk_integration(resource, input_data):
"""Dispatch arn:aws:states:::aws-sdk:<service>:<action> to the target MiniStack service."""
# Parse service and action from ARN
@@ -2210,15 +2346,17 @@ def _invoke_aws_sdk_integration(resource, input_data):
)
protocol = service_info["protocol"]
- if protocol != "json":
+ if protocol == "json":
+ return _dispatch_aws_sdk_json(service_info, service_name, action, input_data)
+ elif protocol == "query":
+ return _dispatch_aws_sdk_query(service_info, service_name, action, input_data)
+ else:
raise _ExecutionError(
"States.Runtime",
f"aws-sdk integration for {protocol}-protocol service '{service_name}' "
"is not yet implemented; use native service integrations instead",
)
- return _dispatch_aws_sdk_json(service_info, service_name, action, input_data)
-
_SERVICE_DISPATCH = {
"arn:aws:states:::sqs:sendMessage": _invoke_sqs_send_message,
diff --git a/tests/test_services.py b/tests/test_services.py
index 04efc617..002d904c 100644
--- a/tests/test_services.py
+++ b/tests/test_services.py
@@ -4574,40 +4574,39 @@ def test_sfn_aws_sdk_unknown_service_fails(sfn, sfn_sync):
# ===================================================================
-# Step Functions aws-sdk:secretsmanager — comprehensive dispatch tests
+# Step Functions aws-sdk:rds — query-protocol dispatch tests
# ===================================================================
-def test_sfn_aws_sdk_secretsmanager_put_and_get(sfn, sfn_sync, sm):
- """aws-sdk:secretsmanager PutSecretValue then GetSecretValue round-trip."""
+def test_sfn_aws_sdk_rds_create_and_describe_cluster(sfn, sfn_sync):
+ """aws-sdk:rds CreateDBCluster + DescribeDBClusters via query-protocol dispatch."""
import uuid as _uuid
- secret_name = f"sfn-sdk-put-get-{_uuid.uuid4().hex[:8]}"
- sm_name = f"sdk-sm-put-{_uuid.uuid4().hex[:8]}"
-
- # Pre-create the secret so we can PutSecretValue to it
- sm.create_secret(Name=secret_name, SecretString="initial")
+ cluster_id = f"sfn-rds-{_uuid.uuid4().hex[:8]}"
+ sm_name = f"sdk-rds-create-{_uuid.uuid4().hex[:8]}"
definition = json.dumps({
- "StartAt": "PutValue",
+ "StartAt": "CreateCluster",
"States": {
- "PutValue": {
+ "CreateCluster": {
"Type": "Task",
- "Resource": "arn:aws:states:::aws-sdk:secretsmanager:PutSecretValue",
+ "Resource": "arn:aws:states:::aws-sdk:rds:CreateDBCluster",
"Parameters": {
- "SecretId": secret_name,
- "SecretString": "updated-via-sfn",
+ "DBClusterIdentifier": cluster_id,
+ "Engine": "aurora-postgresql",
+ "MasterUsername": "admin",
+ "MasterUserPassword": "testpass123",
},
- "ResultPath": "$.putResult",
- "Next": "GetValue",
+ "ResultPath": "$.createResult",
+ "Next": "DescribeClusters",
},
- "GetValue": {
+ "DescribeClusters": {
"Type": "Task",
- "Resource": "arn:aws:states:::aws-sdk:secretsmanager:GetSecretValue",
+ "Resource": "arn:aws:states:::aws-sdk:rds:DescribeDBClusters",
"Parameters": {
- "SecretId": secret_name,
+ "DBClusterIdentifier": cluster_id,
},
- "ResultPath": "$.getResult",
+ "ResultPath": "$.describeResult",
"Next": "Done",
},
"Done": {"Type": "Succeed"},
@@ -4623,71 +4622,47 @@ def test_sfn_aws_sdk_secretsmanager_put_and_get(sfn, sfn_sync, sm):
resp = sfn_sync.start_sync_execution(stateMachineArn=sm_arn, input=json.dumps({}))
assert resp["status"] == "SUCCEEDED", f"Execution failed: {resp.get('error')} — {resp.get('cause')}"
output = json.loads(resp["output"])
- assert output["getResult"]["SecretString"] == "updated-via-sfn"
- assert output["putResult"]["Name"] == secret_name
+
+ # Verify create result contains the cluster
+ create_cluster = output["createResult"]["DBCluster"]
+ assert create_cluster["DBClusterIdentifier"] == cluster_id
+ assert create_cluster["Engine"] == "aurora-postgresql"
+
+ # Verify describe result
+ describe_clusters = output["describeResult"]["DBClusters"]
+ assert "DBCluster" in describe_clusters
sfn_sync.delete_state_machine(stateMachineArn=sm_arn)
-def test_sfn_aws_sdk_secretsmanager_get_random_password(sfn, sfn_sync):
- """aws-sdk:secretsmanager GetRandomPassword returns a password string."""
+def test_sfn_aws_sdk_rds_create_and_describe_instance(sfn, sfn_sync):
+ """aws-sdk:rds CreateDBInstance + DescribeDBInstances via query-protocol dispatch."""
import uuid as _uuid
- sm_name = f"sdk-sm-rndpw-{_uuid.uuid4().hex[:8]}"
+ instance_id = f"sfn-inst-{_uuid.uuid4().hex[:8]}"
+ sm_name = f"sdk-rds-inst-{_uuid.uuid4().hex[:8]}"
definition = json.dumps({
- "StartAt": "GetPassword",
+ "StartAt": "CreateInstance",
"States": {
- "GetPassword": {
+ "CreateInstance": {
"Type": "Task",
- "Resource": "arn:aws:states:::aws-sdk:secretsmanager:GetRandomPassword",
+ "Resource": "arn:aws:states:::aws-sdk:rds:CreateDBInstance",
"Parameters": {
- "PasswordLength": 20,
- "ExcludePunctuation": True,
+ "DBInstanceIdentifier": instance_id,
+ "DBInstanceClass": "db.t3.micro",
+ "Engine": "postgres",
},
- "ResultPath": "$.passwordResult",
- "Next": "Done",
+ "ResultPath": "$.createResult",
+ "Next": "DescribeInstances",
},
- "Done": {"Type": "Succeed"},
- },
- })
-
- sm_arn = sfn_sync.create_state_machine(
- name=sm_name,
- definition=definition,
- roleArn="arn:aws:iam::000000000000:role/sfn-role",
- )["stateMachineArn"]
-
- resp = sfn_sync.start_sync_execution(stateMachineArn=sm_arn, input=json.dumps({}))
- assert resp["status"] == "SUCCEEDED", f"Execution failed: {resp.get('error')} — {resp.get('cause')}"
- output = json.loads(resp["output"])
- pw = output["passwordResult"]["RandomPassword"]
- assert isinstance(pw, str)
- assert len(pw) == 20
-
- sfn_sync.delete_state_machine(stateMachineArn=sm_arn)
-
-
-def test_sfn_aws_sdk_secretsmanager_delete(sfn, sfn_sync, sm):
- """aws-sdk:secretsmanager DeleteSecret marks a secret for deletion."""
- import uuid as _uuid
-
- secret_name = f"sfn-sdk-del-{_uuid.uuid4().hex[:8]}"
- sm_name = f"sdk-sm-del-{_uuid.uuid4().hex[:8]}"
-
- sm.create_secret(Name=secret_name, SecretString="to-delete")
-
- definition = json.dumps({
- "StartAt": "DeleteSecret",
- "States": {
- "DeleteSecret": {
+ "DescribeInstances": {
"Type": "Task",
- "Resource": "arn:aws:states:::aws-sdk:secretsmanager:DeleteSecret",
+ "Resource": "arn:aws:states:::aws-sdk:rds:DescribeDBInstances",
"Parameters": {
- "SecretId": secret_name,
- "ForceDeleteWithoutRecovery": True,
+ "DBInstanceIdentifier": instance_id,
},
- "ResultPath": "$.deleteResult",
+ "ResultPath": "$.describeResult",
"Next": "Done",
},
"Done": {"Type": "Succeed"},
@@ -4703,67 +4678,40 @@ def test_sfn_aws_sdk_secretsmanager_delete(sfn, sfn_sync, sm):
resp = sfn_sync.start_sync_execution(stateMachineArn=sm_arn, input=json.dumps({}))
assert resp["status"] == "SUCCEEDED", f"Execution failed: {resp.get('error')} — {resp.get('cause')}"
output = json.loads(resp["output"])
- assert output["deleteResult"]["Name"] == secret_name
+
+ create_inst = output["createResult"]["DBInstance"]
+ assert create_inst["DBInstanceIdentifier"] == instance_id
+ assert create_inst["Engine"] == "postgres"
sfn_sync.delete_state_machine(stateMachineArn=sm_arn)
-def test_sfn_aws_sdk_secretsmanager_full_lifecycle(sfn, sfn_sync):
- """Full lifecycle via aws-sdk: create → put → get → describe → delete."""
+def test_sfn_aws_sdk_rds_modify_cluster(sfn, sfn_sync, rds):
+ """aws-sdk:rds ModifyDBCluster via query-protocol dispatch."""
import uuid as _uuid
- secret_name = f"sfn-sdk-lifecycle-{_uuid.uuid4().hex[:8]}"
- sm_name = f"sdk-sm-lifecycle-{_uuid.uuid4().hex[:8]}"
+ cluster_id = f"sfn-mod-{_uuid.uuid4().hex[:8]}"
+ sm_name = f"sdk-rds-mod-{_uuid.uuid4().hex[:8]}"
+
+ # Pre-create cluster directly
+ rds.create_db_cluster(
+ DBClusterIdentifier=cluster_id,
+ Engine="aurora-postgresql",
+ MasterUsername="admin",
+ MasterUserPassword="testpass123",
+ )
definition = json.dumps({
- "StartAt": "Create",
+ "StartAt": "ModifyCluster",
"States": {
- "Create": {
- "Type": "Task",
- "Resource": "arn:aws:states:::aws-sdk:secretsmanager:CreateSecret",
- "Parameters": {
- "Name": secret_name,
- "SecretString": "step1",
- },
- "ResultPath": "$.createResult",
- "Next": "Put",
- },
- "Put": {
- "Type": "Task",
- "Resource": "arn:aws:states:::aws-sdk:secretsmanager:PutSecretValue",
- "Parameters": {
- "SecretId": secret_name,
- "SecretString": "step2",
- },
- "ResultPath": "$.putResult",
- "Next": "Get",
- },
- "Get": {
- "Type": "Task",
- "Resource": "arn:aws:states:::aws-sdk:secretsmanager:GetSecretValue",
- "Parameters": {
- "SecretId": secret_name,
- },
- "ResultPath": "$.getResult",
- "Next": "Describe",
- },
- "Describe": {
+ "ModifyCluster": {
"Type": "Task",
- "Resource": "arn:aws:states:::aws-sdk:secretsmanager:DescribeSecret",
+ "Resource": "arn:aws:states:::aws-sdk:rds:ModifyDBCluster",
"Parameters": {
- "SecretId": secret_name,
+ "DBClusterIdentifier": cluster_id,
+ "BackupRetentionPeriod": "7",
},
- "ResultPath": "$.describeResult",
- "Next": "Delete",
- },
- "Delete": {
- "Type": "Task",
- "Resource": "arn:aws:states:::aws-sdk:secretsmanager:DeleteSecret",
- "Parameters": {
- "SecretId": secret_name,
- "ForceDeleteWithoutRecovery": True,
- },
- "ResultPath": "$.deleteResult",
+ "ResultPath": "$.modifyResult",
"Next": "Done",
},
"Done": {"Type": "Succeed"},
@@ -4779,43 +4727,25 @@ def test_sfn_aws_sdk_secretsmanager_full_lifecycle(sfn, sfn_sync):
resp = sfn_sync.start_sync_execution(stateMachineArn=sm_arn, input=json.dumps({}))
assert resp["status"] == "SUCCEEDED", f"Execution failed: {resp.get('error')} — {resp.get('cause')}"
output = json.loads(resp["output"])
-
- # Verify create
- assert output["createResult"]["Name"] == secret_name
- assert "ARN" in output["createResult"]
-
- # Verify put
- assert output["putResult"]["Name"] == secret_name
- assert "VersionId" in output["putResult"]
-
- # Verify get — should have the updated value
- assert output["getResult"]["SecretString"] == "step2"
- assert output["getResult"]["Name"] == secret_name
-
- # Verify describe
- assert output["describeResult"]["Name"] == secret_name
- assert "ARN" in output["describeResult"]
-
- # Verify delete
- assert output["deleteResult"]["Name"] == secret_name
+ assert output["modifyResult"]["DBCluster"]["BackupRetentionPeriod"] == "7"
sfn_sync.delete_state_machine(stateMachineArn=sm_arn)
-def test_sfn_aws_sdk_secretsmanager_not_found_error(sfn, sfn_sync):
- """aws-sdk:secretsmanager GetSecretValue on missing secret propagates error."""
+def test_sfn_aws_sdk_rds_not_found_error(sfn, sfn_sync):
+ """aws-sdk:rds DescribeDBClusters on missing cluster propagates error."""
import uuid as _uuid
- sm_name = f"sdk-sm-notfound-{_uuid.uuid4().hex[:8]}"
+ sm_name = f"sdk-rds-notfound-{_uuid.uuid4().hex[:8]}"
definition = json.dumps({
- "StartAt": "GetMissing",
+ "StartAt": "DescribeMissing",
"States": {
- "GetMissing": {
+ "DescribeMissing": {
"Type": "Task",
- "Resource": "arn:aws:states:::aws-sdk:secretsmanager:GetSecretValue",
+ "Resource": "arn:aws:states:::aws-sdk:rds:DescribeDBClusters",
"Parameters": {
- "SecretId": "this-secret-does-not-exist",
+ "DBClusterIdentifier": "this-cluster-does-not-exist",
},
"End": True,
},
@@ -4830,7 +4760,7 @@ def test_sfn_aws_sdk_secretsmanager_not_found_error(sfn, sfn_sync):
resp = sfn_sync.start_sync_execution(stateMachineArn=sm_arn, input=json.dumps({}))
assert resp["status"] == "FAILED"
- assert "ResourceNotFoundException" in (resp.get("error", "") + resp.get("cause", ""))
+ assert "DBClusterNotFoundFault" in (resp.get("error", "") + resp.get("cause", ""))
sfn_sync.delete_state_machine(stateMachineArn=sm_arn)