Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.
Python awsaws-emulatoraws-localaws-sdkdevtoolsdockerdynamodbec2emulatorlambdalocalstacklocalstack-alternativeministackmock-awsopen-sourcepythons3sqsterraform
feat: add query-protocol aws-sdk:* task dispatcher for Step Functions (#174)
Jay Janssen103316fa4d57
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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### Addeddiff --git a/ministack/services/stepfunctions.py b/ministack/services/stepfunctions.pyindex 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.pyindex 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_clusterssfn_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)