Skip to content

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

feat(stepfunctions): add state machine versioning API (#470)

W. H. Wang247bf83d5977
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.
### Fixed
diff --git a/ministack/services/stepfunctions.py b/ministack/services/stepfunctions.py
index 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.py
index 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)