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(stepfunctions): add state machine versioning API (#470)
W. H. Wang247bf83d5977
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex bb17719b..ad664b02 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -10,6 +10,7 @@ Versioning follows [Semantic Versioning](https://semver.org/).## [Unreleased]### Added+- **Step Functions versioning API** — `PublishStateMachineVersion`, `DeleteStateMachineVersion`, `ListStateMachineVersions`, plus `DescribeStateMachine` support for qualified version ARNs (`arn:…:stateMachine:<name>:<N>`) returning the snapshot captured at publish time. `CreateStateMachine` now accepts the `publish=True` parameter, returning `stateMachineVersionArn` for the auto-published v1 in the same call. AWS-style optimistic concurrency via `revisionId`: every Create/Update rotates the state machine's `revisionId`, and `PublishStateMachineVersion`'s optional `revisionId` is treated as a precondition — supplying a stale value raises `ConflictException`. Version numbers are monotonic per state machine and never reused after delete (a `lastVersionNumber` high-water mark on the base state machine enforces this, matching AWS's documented behaviour). Without these actions, terraform-provider-aws v6 fails on every `aws_sfn_state_machine` refresh because it unconditionally calls `ListStateMachineVersions` regardless of whether versioning was opted into.- **CloudWatch Logs Delivery API** — `PutDeliverySource` / `GetDeliverySource` / `DeleteDeliverySource` / `DescribeDeliverySources`, `PutDeliveryDestination` / `GetDeliveryDestination` / `DeleteDeliveryDestination` / `DescribeDeliveryDestinations`, and `CreateDelivery` / `GetDelivery` / `DeleteDelivery` / `DescribeDeliveries` (12 actions total). This is the 2023-era replacement for subscription filters that vended-logs producers (Bedrock, AppSync, CodeWhisperer, …) use to ship logs into S3, CloudWatch Logs, or Firehose. Server-derived fields match AWS's contract: `service` is computed from a delivery source's `resourceArn` (e.g. `arn:aws:bedrock:…` → `bedrock`) and `deliveryDestinationType` from a destination's `destinationResourceArn` (`s3` → `S3`, `logs` → `CWL`, `firehose` → `FH`); callers cannot override either. `outputFormat` is validated against the AWS enum (`json` / `plain` / `w3c` / `raw` / `parquet`). `CreateDelivery` requires the `deliveryDestinationArn` to resolve to an already-registered destination (instead of silently defaulting to `CWL`) and rejects duplicate `(deliverySourceName, deliveryDestinationArn)` pairs with `ConflictException`, matching AWS's one-Delivery-per-pair contract.### Fixeddiff --git a/ministack/services/stepfunctions.py b/ministack/services/stepfunctions.pyindex 42226a23..e002fca2 100644--- a/ministack/services/stepfunctions.py+++ b/ministack/services/stepfunctions.py@@ -10,7 +10,9 @@ Supports: CreateStateMachine, DeleteStateMachine, DescribeStateMachine,SendTaskSuccess, SendTaskFailure, SendTaskHeartbeat,CreateActivity, DeleteActivity, DescribeActivity, ListActivities,GetActivityTask,- TagResource, UntagResource, ListTagsForResource.+ TagResource, UntagResource, ListTagsForResource,+ PublishStateMachineVersion, DeleteStateMachineVersion,+ ListStateMachineVersions.ASL state types: Pass, Task, Choice, Wait, Succeed, Fail, Parallel, Map.Task states invoke Lambda functions via services.lambda_svc when available.@@ -119,6 +121,12 @@ _tags = AccountScopedDict()_activities = AccountScopedDict()_activity_tasks = AccountScopedDict()+# version_arn -> {stateMachineVersionArn, stateMachineRevisionId,+# description, creationDate, definition, roleArn, type,+# loggingConfiguration}+# Version ARN shape: arn:aws:states:<region>:<acct>:stateMachine:<name>:<N>+_state_machine_versions = AccountScopedDict()+# ── Persistence ────────────────────────────────────────────def get_state():@@ -127,6 +135,7 @@ def get_state():"executions": copy.deepcopy(_executions),"tags": copy.deepcopy(_tags),"activities": copy.deepcopy(_activities),+ "state_machine_versions": copy.deepcopy(_state_machine_versions),}@@ -137,6 +146,7 @@ def restore_state(data):_executions.update(data.get("executions", {}))_tags.update(data.get("tags", {}))_activities.update(data.get("activities", {}))+ _state_machine_versions.update(data.get("state_machine_versions", {}))# Executions that were RUNNING when the process died cannot resume —# mark them FAILED, following the ECS precedent (tasks → STOPPED).for exc in _executions.values():@@ -246,6 +256,9 @@ async def handle_request(method, path, headers, body, query_params):"GetActivityTask": _get_activity_task,"TestState": _test_state,"ValidateStateMachineDefinition": _validate_state_machine_definition,+ "PublishStateMachineVersion": _publish_state_machine_version,+ "DeleteStateMachineVersion": _delete_state_machine_version,+ "ListStateMachineVersions": _list_state_machine_versions,}handler = handlers.get(action)@@ -284,13 +297,43 @@ def _create_state_machine(data):"loggingConfiguration": data.get("loggingConfiguration",{"level": "OFF", "includeExecutionData": False}),+ # AWS rotates revisionId on every Create/Update. Callers use it+ # as an optimistic-concurrency precondition when publishing a+ # version (see _publish_state_machine_version).+ "revisionId": new_uuid(),+ # Monotonic high-water mark for published version numbers. AWS+ # never reuses a version number after delete (publish v1, v2,+ # v3, delete v3 → next publish is v4, not v3). Tracking the+ # mark here, rather than scanning surviving versions, preserves+ # that invariant.+ "lastVersionNumber": 0,}tags = data.get("tags", [])if tags:_tags[arn] = list(tags)- return json_response({"stateMachineArn": arn, "creationDate": ts})+ response = {"stateMachineArn": arn, "creationDate": ts}+ # AWS CreateStateMachine accepts publish=True to auto-publish v1+ # in the same call; response carries stateMachineVersionArn.+ if data.get("publish"):+ _state_machines[arn]["lastVersionNumber"] += 1+ next_number = _state_machines[arn]["lastVersionNumber"]+ version_arn = f"{arn}:{next_number}"+ _state_machine_versions[version_arn] = {+ "stateMachineVersionArn": version_arn,+ "stateMachineArn": arn,+ "stateMachineRevisionId": _state_machines[arn]["revisionId"],+ "description": data.get("versionDescription", ""),+ "creationDate": ts,+ "definition": _state_machines[arn]["definition"],+ "roleArn": _state_machines[arn]["roleArn"],+ "type": _state_machines[arn]["type"],+ "loggingConfiguration": copy.deepcopy(+ _state_machines[arn]["loggingConfiguration"]),+ }+ response["stateMachineVersionArn"] = version_arn+ return json_response(response)def _delete_state_machine(data):@@ -311,11 +354,31 @@ def _delete_state_machine(data):def _describe_state_machine(data):arn = data.get("stateMachineArn")sm = _state_machines.get(arn)- if not sm:- return error_response_json(- "StateMachineDoesNotExist",- f"State machine {arn} not found", 400)- return json_response(sm)+ if sm:+ return json_response(sm)+ # AWS's DescribeStateMachine also accepts a qualified version ARN+ # (arn:...:stateMachine:<name>:<N>) and returns the snapshot+ # captured at publish time, with stateMachineArn echoing the+ # qualified form.+ version = _state_machine_versions.get(arn) if arn else None+ if version:+ base_sm = _state_machines.get(version["stateMachineArn"]) or {}+ return json_response({+ "stateMachineArn": version["stateMachineVersionArn"],+ "name": base_sm.get("name", ""),+ "definition": version.get("definition") or base_sm.get("definition", "{}"),+ "roleArn": version.get("roleArn") or base_sm.get("roleArn", ""),+ "type": version.get("type") or base_sm.get("type", "STANDARD"),+ "creationDate": version.get("creationDate"),+ "status": "ACTIVE",+ "description": version.get("description", ""),+ "loggingConfiguration": version.get("loggingConfiguration")+ or base_sm.get("loggingConfiguration", {"level": "OFF"}),+ "revisionId": version.get("stateMachineRevisionId", ""),+ })+ return error_response_json(+ "StateMachineDoesNotExist",+ f"State machine {arn} not found", 400)def _update_state_machine(data):@@ -331,7 +394,33 @@ def _update_state_machine(data):sm["roleArn"] = data["roleArn"]if "loggingConfiguration" in data:sm["loggingConfiguration"] = data["loggingConfiguration"]- return json_response({"updateDate": now_iso()})+ # Rotate revisionId so subsequent PublishStateMachineVersion calls+ # with a stale caller-supplied revisionId raise ConflictException+ # (matches AWS optimistic-concurrency semantics).+ sm["revisionId"] = new_uuid()+ ts = now_iso()+ response = {"updateDate": ts}+ # UpdateStateMachine also supports publish=True, which atomically+ # publishes a new version with the post-update state; response+ # carries the new stateMachineVersionArn. Mirrors AWS.+ if data.get("publish"):+ sm["lastVersionNumber"] = sm.get("lastVersionNumber", 0) + 1+ next_number = sm["lastVersionNumber"]+ version_arn = f"{arn}:{next_number}"+ _state_machine_versions[version_arn] = {+ "stateMachineVersionArn": version_arn,+ "stateMachineArn": arn,+ "stateMachineRevisionId": sm["revisionId"],+ "description": data.get("versionDescription", ""),+ "creationDate": ts,+ "definition": sm["definition"],+ "roleArn": sm["roleArn"],+ "type": sm["type"],+ "loggingConfiguration": copy.deepcopy(sm["loggingConfiguration"]),+ }+ response["stateMachineVersionArn"] = version_arn+ response["revisionId"] = sm["revisionId"]+ return json_response(response)def _list_state_machines(data):@@ -2800,3 +2889,103 @@ def reset():_tags.clear()_activities.clear()_activity_tasks.clear()+ _state_machine_versions.clear()+++# ---------------------------------------------------------------------------+# State machine version CRUD+# ---------------------------------------------------------------------------++def _publish_state_machine_version(data):+ """Publish a new version of a state machine.++ The version snapshots the current definition/roleArn/etc. Version+ numbers are monotonic per state machine starting at 1.++ ``revisionId`` (optional) is the AWS optimistic-concurrency+ precondition: if supplied and the state machine's current revisionId+ doesn't match, AWS returns ConflictException. Callers use this to+ refuse publishing a snapshot that has shifted under them.+ """+ arn = data.get("stateMachineArn")+ sm = _state_machines.get(arn)+ if not sm:+ return error_response_json(+ "StateMachineDoesNotExist",+ f"State machine {arn} not found", 400)++ # AWS optimistic-concurrency check: the caller can supply a+ # revisionId they last read from the state machine; if it no longer+ # matches, something updated the state machine in between and the+ # caller should re-read before publishing.+ requested_revision = data.get("revisionId")+ if requested_revision and requested_revision != sm.get("revisionId"):+ return error_response_json(+ "ConflictException",+ "Request cannot be applied because the state machine's "+ "revisionId has changed since the supplied revisionId was read.",+ 400,+ )++ # Bump the per-state-machine high-water mark. AWS never reuses a+ # version number after delete (publish v1, v2, v3, delete v3 →+ # next publish is v4); tracking the mark on the base SM rather+ # than scanning surviving versions preserves that invariant.+ sm["lastVersionNumber"] = sm.get("lastVersionNumber", 0) + 1+ next_number = sm["lastVersionNumber"]++ version_arn = f"{arn}:{next_number}"+ ts = now_iso()+ # Snapshot the current state machine's revisionId into the version+ # so Describe on the version ARN can echo it back.+ snapshot_revision = sm.get("revisionId", "")+ _state_machine_versions[version_arn] = {+ "stateMachineVersionArn": version_arn,+ "stateMachineArn": arn,+ "stateMachineRevisionId": snapshot_revision,+ "description": data.get("description", ""),+ "creationDate": ts,+ "definition": sm.get("definition", "{}"),+ "roleArn": sm.get("roleArn", ""),+ "type": sm.get("type", "STANDARD"),+ "loggingConfiguration": copy.deepcopy(+ sm.get("loggingConfiguration", {"level": "OFF"})),+ }+ return json_response({+ "stateMachineVersionArn": version_arn,+ "creationDate": ts,+ })+++def _delete_state_machine_version(data):+ version_arn = data.get("stateMachineVersionArn")+ if version_arn not in _state_machine_versions:+ # AWS semantics: DeleteStateMachineVersion on a nonexistent version+ # is a no-op (200 OK), matching other idempotent delete APIs.+ return json_response({})+ del _state_machine_versions[version_arn]+ return json_response({})+++def _list_state_machine_versions(data):+ arn = data.get("stateMachineArn")+ if arn not in _state_machines:+ return error_response_json(+ "StateMachineDoesNotExist",+ f"State machine {arn} not found", 400)++ matching = []+ for version_arn, version in _state_machine_versions.items():+ if version["stateMachineArn"] != arn:+ continue+ matching.append({+ "stateMachineVersionArn": version_arn,+ "creationDate": version["creationDate"],+ })+ # AWS returns versions in descending creationDate order (newest first).+ matching.sort(key=lambda v: v["creationDate"], reverse=True)++ max_results = data.get("maxResults") or len(matching)+ return json_response({+ "stateMachineVersions": matching[:max_results],+ })diff --git a/tests/test_sfn.py b/tests/test_sfn.pyindex 52669813..3feaa2b3 100644--- a/tests/test_sfn.py+++ b/tests/test_sfn.py@@ -2733,3 +2733,211 @@ def test_sfn_wait_scale_zero_skips_wait(sfn):sfn.delete_state_machine(stateMachineArn=sm_arn)finally:_set_wait_scale(1.0)+++# ---------------------------------------------------------------------------+# Step Functions versioning (PublishStateMachineVersion / List / Delete)+# ---------------------------------------------------------------------------++def test_sfn_publish_state_machine_version(sfn):+ """Publish two versions, list them, delete one, re-list.++ Without this action AWS SDK calls (boto3, botocore, etc.) to+ ``ListStateMachineVersions`` returned ``InvalidAction: Unknown+ action``. (terraform only) terraform-provider-aws 6.x calls this+ action unconditionally on every ``aws_sfn_state_machine`` refresh,+ so the missing action also broke ``terraform plan`` even when no+ versioning was configured.+ """+ uid = _uuid_mod.uuid4().hex[:8]+ name = f"version-test-{uid}"+ definition = json.dumps({+ "StartAt": "P",+ "States": {"P": {"Type": "Pass", "End": True}},+ })+ sm = sfn.create_state_machine(+ name=name,+ definition=definition,+ roleArn="arn:aws:iam::000000000000:role/r",+ )+ sm_arn = sm["stateMachineArn"]++ try:+ # List with no versions → empty.+ listed = sfn.list_state_machine_versions(stateMachineArn=sm_arn)+ assert listed["stateMachineVersions"] == []++ # Publish v1 + v2.+ v1 = sfn.publish_state_machine_version(+ stateMachineArn=sm_arn, description="first",+ )+ assert v1["stateMachineVersionArn"] == f"{sm_arn}:1"++ v2 = sfn.publish_state_machine_version(+ stateMachineArn=sm_arn, description="second",+ )+ assert v2["stateMachineVersionArn"] == f"{sm_arn}:2"++ # List — newest first.+ listed = sfn.list_state_machine_versions(stateMachineArn=sm_arn)+ arns = [v["stateMachineVersionArn"] for v in listed["stateMachineVersions"]]+ assert arns == [f"{sm_arn}:2", f"{sm_arn}:1"]++ # Delete v1; v2 remains.+ sfn.delete_state_machine_version(stateMachineVersionArn=f"{sm_arn}:1")+ listed = sfn.list_state_machine_versions(stateMachineArn=sm_arn)+ assert [v["stateMachineVersionArn"] for v in listed["stateMachineVersions"]] == [f"{sm_arn}:2"]+ finally:+ sfn.delete_state_machine(stateMachineArn=sm_arn)+++def test_sfn_publish_state_machine_version_revisionid_precondition(sfn):+ """revisionId is an AWS optimistic-concurrency precondition.++ Publish with a stale revisionId raises ConflictException. Publish with+ no revisionId (or the current one) succeeds. After UpdateStateMachine+ the revisionId rotates, so a previously valid revisionId becomes stale.+ """+ uid = _uuid_mod.uuid4().hex[:8]+ name = f"version-rev-{uid}"+ sm = sfn.create_state_machine(+ name=name,+ definition=json.dumps({"StartAt": "P", "States": {"P": {"Type": "Pass", "End": True}}}),+ roleArn="arn:aws:iam::000000000000:role/r",+ )+ sm_arn = sm["stateMachineArn"]++ try:+ current_rev = sfn.describe_state_machine(stateMachineArn=sm_arn)["revisionId"]++ # Supplying the current revisionId passes the precondition.+ v1 = sfn.publish_state_machine_version(+ stateMachineArn=sm_arn, revisionId=current_rev,+ )+ assert v1["stateMachineVersionArn"] == f"{sm_arn}:1"++ # UpdateStateMachine rotates revisionId.+ sfn.update_state_machine(+ stateMachineArn=sm_arn,+ definition=json.dumps({+ "StartAt": "P",+ "States": {"P": {"Type": "Pass", "Result": "changed", "End": True}},+ }),+ )+ rev_after_update = sfn.describe_state_machine(stateMachineArn=sm_arn)["revisionId"]+ assert rev_after_update != current_rev++ # The old revisionId is now stale; Publish with it raises.+ with pytest.raises(ClientError) as exc:+ sfn.publish_state_machine_version(+ stateMachineArn=sm_arn, revisionId=current_rev,+ )+ assert exc.value.response["Error"]["Code"] == "ConflictException"++ # Publish without revisionId always succeeds (no precondition).+ v2 = sfn.publish_state_machine_version(stateMachineArn=sm_arn)+ assert v2["stateMachineVersionArn"] == f"{sm_arn}:2"+ finally:+ sfn.delete_state_machine(stateMachineArn=sm_arn)+++def test_sfn_describe_state_machine_on_version_arn(sfn):+ """DescribeStateMachine accepts a qualified version ARN and returns+ the snapshot captured at publish time."""+ uid = _uuid_mod.uuid4().hex[:8]+ name = f"describe-version-{uid}"+ initial_definition = json.dumps({+ "StartAt": "P",+ "States": {"P": {"Type": "Pass", "Result": "v1", "End": True}},+ })+ sm = sfn.create_state_machine(+ name=name, definition=initial_definition,+ roleArn="arn:aws:iam::000000000000:role/r",+ )+ sm_arn = sm["stateMachineArn"]++ try:+ v1 = sfn.publish_state_machine_version(+ stateMachineArn=sm_arn, description="first-snapshot",+ )++ # Mutate the base state machine so v1's definition differs from+ # the current one — tests that describe-on-version returns the+ # snapshot, not the live state.+ sfn.update_state_machine(+ stateMachineArn=sm_arn,+ definition=json.dumps({+ "StartAt": "P",+ "States": {"P": {"Type": "Pass", "Result": "v-live", "End": True}},+ }),+ )++ described = sfn.describe_state_machine(+ stateMachineArn=v1["stateMachineVersionArn"],+ )+ assert described["stateMachineArn"] == v1["stateMachineVersionArn"]+ assert described["description"] == "first-snapshot"+ # Definition echoed back is v1's snapshot, not the live one.+ assert json.loads(described["definition"])["States"]["P"]["Result"] == "v1"+ finally:+ sfn.delete_state_machine(stateMachineArn=sm_arn)+++def test_sfn_list_state_machine_versions_missing_state_machine(sfn):+ """List against a nonexistent state machine ARN → StateMachineDoesNotExist."""+ missing_arn = "arn:aws:states:us-east-1:000000000000:stateMachine:does-not-exist-xyz"+ with pytest.raises(ClientError) as exc:+ sfn.list_state_machine_versions(stateMachineArn=missing_arn)+ assert exc.value.response["Error"]["Code"] == "StateMachineDoesNotExist"+++def test_sfn_create_state_machine_publish_true_returns_version_arn(sfn):+ """CreateStateMachine with publish=True auto-creates v1 and carries+ stateMachineVersionArn in the response, matching AWS's contract+ for the publish parameter."""+ uid = _uuid_mod.uuid4().hex[:8]+ name = f"pub-create-{uid}"+ resp = sfn.create_state_machine(+ name=name,+ definition=json.dumps({"StartAt": "P", "States": {"P": {"Type": "Pass", "End": True}}}),+ roleArn="arn:aws:iam::000000000000:role/r",+ publish=True,+ )+ sm_arn = resp["stateMachineArn"]+ try:+ assert resp["stateMachineVersionArn"] == f"{sm_arn}:1"+ listed = sfn.list_state_machine_versions(stateMachineArn=sm_arn)+ assert len(listed["stateMachineVersions"]) == 1+ assert listed["stateMachineVersions"][0]["stateMachineVersionArn"] == f"{sm_arn}:1"+ finally:+ sfn.delete_state_machine(stateMachineArn=sm_arn)+++def test_sfn_publish_state_machine_version_numbers_never_reused(sfn):+ """AWS never reuses a version number after delete: publish v1, v2,+ v3, delete v3, publish again → v4 (not v3)."""+ uid = _uuid_mod.uuid4().hex[:8]+ name = f"version-monotonic-{uid}"+ sm = sfn.create_state_machine(+ name=name,+ definition=json.dumps({"StartAt": "P", "States": {"P": {"Type": "Pass", "End": True}}}),+ roleArn="arn:aws:iam::000000000000:role/r",+ )+ sm_arn = sm["stateMachineArn"]+ try:+ v1 = sfn.publish_state_machine_version(stateMachineArn=sm_arn)+ v2 = sfn.publish_state_machine_version(stateMachineArn=sm_arn)+ v3 = sfn.publish_state_machine_version(stateMachineArn=sm_arn)+ assert v3["stateMachineVersionArn"] == f"{sm_arn}:3"++ # Delete latest, then publish again — must be v4 (not v3).+ sfn.delete_state_machine_version(stateMachineVersionArn=v3["stateMachineVersionArn"])+ v4 = sfn.publish_state_machine_version(stateMachineArn=sm_arn)+ assert v4["stateMachineVersionArn"] == f"{sm_arn}:4"++ # Delete a middle one and republish — also v5, not v3.+ sfn.delete_state_machine_version(stateMachineVersionArn=v2["stateMachineVersionArn"])+ v5 = sfn.publish_state_machine_version(stateMachineArn=sm_arn)+ assert v5["stateMachineVersionArn"] == f"{sm_arn}:5"+ finally:+ sfn.delete_state_machine(stateMachineArn=sm_arn)