Skip to content

armgit / floci

Public Imported from GitHub
0

Light, fluffy, and always free - The AWS Local Emulator alternative

feat(stepfunctions): describe a distributed Map run after it finishes (#2694)

Facundo Paredesff61c2b2a5b8
diff --git a/compatibility-tests/sdk-test-java/src/test/java/com/floci/test/StepFunctionsDescribeMapRunTest.java b/compatibility-tests/sdk-test-java/src/test/java/com/floci/test/StepFunctionsDescribeMapRunTest.java
new file mode 100644
index 0000000000..c046b7bf8d
--- /dev/null
+++ b/compatibility-tests/sdk-test-java/src/test/java/com/floci/test/StepFunctionsDescribeMapRunTest.java
@@ -0,0 +1,200 @@
+package com.floci.test;
+
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.MethodOrderer;
+import org.junit.jupiter.api.Order;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.TestMethodOrder;
+import software.amazon.awssdk.services.s3.S3Client;
+import software.amazon.awssdk.services.s3.model.DeleteBucketRequest;
+import software.amazon.awssdk.services.s3.model.DeleteObjectRequest;
+import software.amazon.awssdk.services.s3.model.ListObjectsV2Response;
+import software.amazon.awssdk.services.s3.model.S3Object;
+import software.amazon.awssdk.services.sfn.SfnClient;
+import software.amazon.awssdk.services.sfn.model.DescribeExecutionResponse;
+import software.amazon.awssdk.services.sfn.model.DescribeMapRunResponse;
+import software.amazon.awssdk.services.sfn.model.ExecutionStatus;
+import software.amazon.awssdk.services.sfn.model.MapRunExecutionCounts;
+import software.amazon.awssdk.services.sfn.model.MapRunItemCounts;
+import software.amazon.awssdk.services.sfn.model.MapRunStatus;
+import software.amazon.awssdk.services.sfn.model.ResourceNotFoundException;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+/**
+ * Compatibility test for DescribeMapRun through the real SFN SDK client.
+ *
+ * <p>StepFunctionsDescribeMapRunIntegrationTest already pins the wire shape and every field
+ * value with RestAssured. This test exists to exercise what that one cannot: the SDK's own
+ * request serialization, endpoint routing and response deserialization for
+ * {@code sfn.describeMapRun(...)}.
+ *
+ * <p>A distributed Map run is only describable once its {@code ResultWriter} has minted the Map
+ * run ARN and returned it in the Map result — the same way an SDK caller obtains it.
+ */
+@DisplayName("SFN DescribeMapRun")
+@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
+class StepFunctionsDescribeMapRunTest {
+
+ private static final String ROLE_ARN = System.getenv("SFN_ROLE_ARN") != null
+ ? System.getenv("SFN_ROLE_ARN")
+ : "arn:aws:iam::000000000000:role/service-role/test-role";
+ /** AWS reports an unbounded Map run as Integer.MAX_VALUE, not as the ASL default of 0. */
+ private static final int UNBOUNDED_CONCURRENCY = 2147483647;
+ private static final ObjectMapper MAPPER = new ObjectMapper();
+
+ private static SfnClient sfn;
+ private static S3Client s3;
+ private static String bucketName;
+ private static String stateMachineArn;
+ private static String executionArn;
+ private static String mapRunArn;
+
+ @BeforeAll
+ static void setup() throws Exception {
+ sfn = TestFixtures.sfnClient();
+ s3 = TestFixtures.s3Client();
+
+ bucketName = TestFixtures.uniqueName("describe-map-run");
+ s3.createBucket(b -> b.bucket(bucketName));
+
+ String definition = """
+ {
+ "QueryLanguage": "JSONata",
+ "StartAt": "Fan",
+ "States": {
+ "Fan": {
+ "Type": "Map",
+ "End": true,
+ "Items": [{"n": 1}, {"n": 2}, {"n": 3}],
+ "ItemProcessor": {
+ "ProcessorConfig": {"Mode": "DISTRIBUTED", "ExecutionType": "STANDARD"},
+ "StartAt": "Keep",
+ "States": {"Keep": {"Type": "Pass", "End": true}}
+ },
+ "ResultWriter": {
+ "Resource": "arn:aws:states:::s3:putObject",
+ "Arguments": {"Bucket": "%s", "Prefix": "out"}
+ }
+ }
+ }
+ }
+ """.formatted(bucketName);
+
+ stateMachineArn = sfn.createStateMachine(b -> b
+ .name(TestFixtures.uniqueName("describe-map-run-sm"))
+ .definition(definition)
+ .roleArn(ROLE_ARN)).stateMachineArn();
+
+ executionArn = sfn.startExecution(b -> b
+ .stateMachineArn(stateMachineArn)
+ .input("{}")).executionArn();
+
+ DescribeExecutionResponse execution = pollUntilDone(executionArn);
+ assertThat(execution.status())
+ .as("cause: %s", execution.cause())
+ .isEqualTo(ExecutionStatus.SUCCEEDED);
+
+ mapRunArn = MAPPER.readTree(execution.output()).path("MapRunArn").asText();
+ assertThat(mapRunArn).contains(":mapRun:");
+ }
+
+ @AfterAll
+ static void cleanup() {
+ if (sfn != null) {
+ if (stateMachineArn != null) {
+ try {
+ sfn.deleteStateMachine(b -> b.stateMachineArn(stateMachineArn));
+ } catch (Exception ignored) {
+ }
+ }
+ sfn.close();
+ }
+ if (s3 != null) {
+ try {
+ ListObjectsV2Response objects = s3.listObjectsV2(b -> b.bucket(bucketName));
+ for (S3Object object : objects.contents()) {
+ s3.deleteObject(DeleteObjectRequest.builder()
+ .bucket(bucketName).key(object.key()).build());
+ }
+ s3.deleteBucket(DeleteBucketRequest.builder().bucket(bucketName).build());
+ } catch (Exception ignored) {
+ }
+ s3.close();
+ }
+ }
+
+ @Test
+ @Order(1)
+ void describeMapRun_deserializesTheFinishedRun() {
+ DescribeMapRunResponse response = sfn.describeMapRun(b -> b.mapRunArn(mapRunArn));
+
+ assertThat(response.status()).isEqualTo(MapRunStatus.SUCCEEDED);
+ assertThat(response.executionArn()).isEqualTo(executionArn);
+ assertThat(response.maxConcurrency()).isEqualTo(UNBOUNDED_CONCURRENCY);
+ assertThat(response.toleratedFailurePercentage()).isEqualTo(0.0f);
+ assertThat(response.toleratedFailureCount()).isEqualTo(0);
+ assertThat(response.redriveCount()).isEqualTo(0);
+
+ assertItemCounts(response.itemCounts());
+ assertExecutionCounts(response.executionCounts());
+ }
+
+ @Test
+ @Order(2)
+ void describeMapRun_unknownArnRaisesResourceNotFound() {
+ String unknown = "arn:aws:states:us-east-1:000000000000:mapRun:"
+ + TestFixtures.uniqueName("no-such-map-run") + "/"
+ + "00000000-0000-0000-0000-000000000000:11111111-1111-1111-1111-111111111111";
+
+ assertThatThrownBy(() -> sfn.describeMapRun(b -> b.mapRunArn(unknown)))
+ .isInstanceOf(ResourceNotFoundException.class)
+ .hasMessageContaining("Resource not found: '" + unknown + "'");
+ }
+
+ // ──────────────────────────── helpers ────────────────────────────
+
+ /** The ten counters of a Map run all of whose three items succeeded. */
+ private static void assertItemCounts(MapRunItemCounts counts) {
+ assertThat(counts.pending()).isEqualTo(0);
+ assertThat(counts.running()).isEqualTo(0);
+ assertThat(counts.succeeded()).isEqualTo(3);
+ assertThat(counts.failed()).isEqualTo(0);
+ assertThat(counts.timedOut()).isEqualTo(0);
+ assertThat(counts.aborted()).isEqualTo(0);
+ assertThat(counts.total()).isEqualTo(3);
+ assertThat(counts.resultsWritten()).isEqualTo(3);
+ assertThat(counts.failuresNotRedrivable()).isEqualTo(0);
+ assertThat(counts.pendingRedrive()).isEqualTo(0);
+ }
+
+ /** One child execution per item: ItemBatcher is not applied, so the shape matches itemCounts. */
+ private static void assertExecutionCounts(MapRunExecutionCounts counts) {
+ assertThat(counts.pending()).isEqualTo(0);
+ assertThat(counts.running()).isEqualTo(0);
+ assertThat(counts.succeeded()).isEqualTo(3);
+ assertThat(counts.failed()).isEqualTo(0);
+ assertThat(counts.timedOut()).isEqualTo(0);
+ assertThat(counts.aborted()).isEqualTo(0);
+ assertThat(counts.total()).isEqualTo(3);
+ assertThat(counts.resultsWritten()).isEqualTo(3);
+ assertThat(counts.failuresNotRedrivable()).isEqualTo(0);
+ assertThat(counts.pendingRedrive()).isEqualTo(0);
+ }
+
+ private static DescribeExecutionResponse pollUntilDone(String execArn) throws InterruptedException {
+ for (int i = 0; i < 150; i++) {
+ DescribeExecutionResponse resp = sfn.describeExecution(b -> b.executionArn(execArn));
+ if (resp.status() != ExecutionStatus.RUNNING) {
+ return resp;
+ }
+ Thread.sleep(100);
+ }
+ throw new AssertionError("Execution did not complete within timeout: " + execArn);
+ }
+}
diff --git a/docs/services/step-functions.md b/docs/services/step-functions.md
index 1baaa580d2..df9b2b4052 100644
--- a/docs/services/step-functions.md
+++ b/docs/services/step-functions.md
@@ -23,6 +23,7 @@
| `ListExecutions` | List executions for a state machine |
| `StopExecution` | Stop a running execution |
| `GetExecutionHistory` | Get the full event history of an execution |
+| `DescribeMapRun` | Get the item and execution counters of a distributed Map run |
| `SendTaskSuccess` | Report task success (for `.waitForTaskToken` tasks) |
| `SendTaskFailure` | Report task failure |
| `SendTaskHeartbeat` | Send a heartbeat for long-running tasks |
diff --git a/src/main/java/io/github/hectorvent/floci/services/stepfunctions/AslExecutor.java b/src/main/java/io/github/hectorvent/floci/services/stepfunctions/AslExecutor.java
index a4c25f9728..526c2bd713 100644
--- a/src/main/java/io/github/hectorvent/floci/services/stepfunctions/AslExecutor.java
+++ b/src/main/java/io/github/hectorvent/floci/services/stepfunctions/AslExecutor.java
@@ -33,6 +33,7 @@ import io.github.hectorvent.floci.services.s3.model.S3Object;
import io.github.hectorvent.floci.services.sqs.SqsJsonHandler;
import io.github.hectorvent.floci.services.stepfunctions.model.Execution;
import io.github.hectorvent.floci.services.stepfunctions.model.HistoryEvent;
+import io.github.hectorvent.floci.services.stepfunctions.model.MapRun;
import io.github.hectorvent.floci.services.stepfunctions.model.MockedResponseStep;
import io.github.hectorvent.floci.services.stepfunctions.model.MockedTestCase;
import io.github.hectorvent.floci.services.stepfunctions.model.StateMachine;
@@ -991,6 +992,7 @@ public class AslExecutor {
case "startSyncExecution" -> invokeAwsSdkSfnStartSyncExecution(input, region);
case "sendTaskSuccess" -> invokeAwsSdkSfnSendTaskSuccess(input);
case "sendTaskFailure" -> invokeAwsSdkSfnSendTaskFailure(input);
+ case "describeMapRun" -> invokeAwsSdkSfnDescribeMapRun(input);
default -> throw new FailStateException("States.TaskFailed",
"Unsupported resource: " + AWS_SDK_SFN_PREFIX + action);
};
@@ -1049,6 +1051,30 @@ public class AslExecutor {
return response;
}
+ /**
+ * AWS SDK integration for {@code sfn:describeMapRun}. The SDK names every field in PascalCase
+ * and renders both dates as ISO-8601, where the wire response of the same run carries epoch
+ * seconds. Recasing that response is what keeps the two renderings of a Map run in step.
+ */
+ private JsonNode invokeAwsSdkSfnDescribeMapRun(JsonNode input) {
+ String mapRunArn = input.path("MapRunArn").asText(null);
+ if (mapRunArn == null || mapRunArn.isBlank()) {
+ throw new FailStateException("Sfn.InvalidArnException",
+ "MapRunArn is required for DescribeMapRun");
+ }
+ MapRun mapRun;
+ try {
+ mapRun = sfnService.get().describeMapRun(mapRunArn);
+ } catch (AwsException e) {
+ throw new FailStateException(sdkExceptionName("Sfn", e.getErrorCode()), e.getMessage());
+ }
+ ObjectNode response = (ObjectNode) recaseKeys(objectMapper,
+ StepFunctionsJsonHandler.describeMapRunResponse(objectMapper, mapRun), true);
+ response.put("StartDate", sdkTimestamp(mapRun.getStartDate()));
+ response.put("StopDate", sdkTimestamp(mapRun.getStopDate()));
+ return response;
+ }
+
/**
* AWS SDK integration for {@code sfn:sendTaskSuccess}. AWS fails the calling task with
* {@code Sfn.InvalidTokenException} when the token names no waiting task, so a token that
@@ -2018,6 +2044,7 @@ public class AslExecutor {
}
mapResult = applyResultWriter(name, stateDef, mapInput, results, childInputs, childTimings,
sm, context, jsonata, variables);
+ recordMapRun(mapResult, context, childTimings, requestedConcurrency);
}
if (jsonata) {
@@ -2070,6 +2097,42 @@ public class AslExecutor {
return Math.min(itemCount, Math.min(requestedLimit, serviceLimit));
}
+ /**
+ * Retains the Map run that {@link #applyResultWriter} just exported, so {@code DescribeMapRun}
+ * can report its counters afterwards. Only an exported run is retained: the Map result is the
+ * one place an ASL author reads the Map run ARN, so a run without a {@code ResultWriter}
+ * {@code Resource} has no ARN anybody could describe.
+ *
+ * <p>The run starts with its first item, taken from the child timings the export record already
+ * collected, and stops here: the {@code ResultWriter} export has just returned, and AWS closes
+ * a Map run's window on the export rather than on the last item. A run over no items starts and
+ * stops at that same instant.
+ */
+ private void recordMapRun(JsonNode mapResult, JsonNode context, List<long[]> childTimings,
+ int requestedConcurrency) {
+ String mapRunArn = mapResult.path("MapRunArn").asText(null);
+ if (mapRunArn == null) {
+ return;
+ }
+ long stop = System.currentTimeMillis();
+ long start = stop;
+ for (long[] timing : childTimings) {
+ start = Math.min(start, timing[0]);
+ }
+
+ MapRun mapRun = new MapRun();
+ mapRun.setMapRunArn(mapRunArn);
+ mapRun.setExecutionArn(context.path("Execution").path("Id").asText(null));
+ mapRun.setStartDate(start / 1000.0);
+ mapRun.setStopDate(stop / 1000.0);
+ mapRun.setItemCount(childTimings.size());
+ // ASL spells an unbounded Map as MaxConcurrency 0, or by omitting it; DescribeMapRun
+ // reports that same run as Integer.MAX_VALUE.
+ mapRun.setMaxConcurrency(
+ requestedConcurrency == 0 ? Integer.MAX_VALUE : requestedConcurrency);
+ sfnService.get().recordMapRun(mapRun);
+ }
+
/**
* Emulates a Distributed Map state's {@code ResultWriter}
* (<a href="https://docs.aws.amazon.com/step-functions/latest/dg/input-output-resultwriter.html">AWS docs</a>).
diff --git a/src/main/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsJsonHandler.java b/src/main/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsJsonHandler.java
index c6784a64b4..c790471e0d 100644
--- a/src/main/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsJsonHandler.java
+++ b/src/main/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsJsonHandler.java
@@ -10,6 +10,7 @@ import io.github.hectorvent.floci.services.stepfunctions.model.Activity;
import io.github.hectorvent.floci.services.stepfunctions.model.ActivityTask;
import io.github.hectorvent.floci.services.stepfunctions.model.Execution;
import io.github.hectorvent.floci.services.stepfunctions.model.HistoryEvent;
+import io.github.hectorvent.floci.services.stepfunctions.model.MapRun;
import io.github.hectorvent.floci.services.stepfunctions.model.StateMachine;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
@@ -48,6 +49,7 @@ public class StepFunctionsJsonHandler {
case "ListExecutions" -> handleListExecutions(request);
case "StopExecution" -> handleStopExecution(request);
case "GetExecutionHistory" -> handleGetExecutionHistory(request);
+ case "DescribeMapRun" -> handleDescribeMapRun(request);
case "SendTaskSuccess" -> handleSendTaskSuccess(request);
case "SendTaskFailure" -> handleSendTaskFailure(request);
case "SendTaskHeartbeat" -> handleSendTaskHeartbeat(request);
@@ -287,6 +289,51 @@ public class StepFunctionsJsonHandler {
return Response.ok(response).build();
}
+ private Response handleDescribeMapRun(JsonNode request) {
+ MapRun mapRun = service.describeMapRun(requiredText(request, "mapRunArn"));
+ return Response.ok(describeMapRunResponse(objectMapper, mapRun)).build();
+ }
+
+ /**
+ * The wire response of {@code DescribeMapRun}, measured against us-east-1. The
+ * {@code arn:aws:states:::aws-sdk:sfn:describeMapRun} Task integration renders the same node in
+ * PascalCase, so this is the one place the response is described.
+ *
+ * <p>A retained run is one whose every item succeeded, because a Map fails on the first item
+ * that fails. That fixes {@code status}, both zero tolerances and {@code redriveCount}:
+ * {@code redriveDate} is absent until a run is redriven, and no run here ever is.
+ */
+ static ObjectNode describeMapRunResponse(ObjectMapper objectMapper, MapRun mapRun) {
+ ObjectNode response = objectMapper.createObjectNode();
+ response.put("mapRunArn", mapRun.getMapRunArn());
+ response.put("executionArn", mapRun.getExecutionArn());
+ response.put("status", "SUCCEEDED");
+ response.put("startDate", mapRun.getStartDate());
+ response.put("stopDate", mapRun.getStopDate());
+ response.put("maxConcurrency", mapRun.getMaxConcurrency());
+ response.put("toleratedFailurePercentage", 0.0);
+ response.put("toleratedFailureCount", 0);
+ putMapRunCounts(response.putObject("itemCounts"), mapRun.getItemCount());
+ // One child execution per item: ItemBatcher is not applied, so no execution covers a batch.
+ putMapRunCounts(response.putObject("executionCounts"), mapRun.getItemCount());
+ response.put("redriveCount", 0);
+ return response;
+ }
+
+ /** The ten counters of a run whose every item succeeded and was written to the result set. */
+ private static void putMapRunCounts(ObjectNode counts, int items) {
+ counts.put("pending", 0);
+ counts.put("running", 0);
+ counts.put("succeeded", items);
+ counts.put("failed", 0);
+ counts.put("timedOut", 0);
+ counts.put("aborted", 0);
+ counts.put("total", items);
+ counts.put("resultsWritten", items);
+ counts.put("failuresNotRedrivable", 0);
+ counts.put("pendingRedrive", 0);
+ }
+
private Response handleListExecutions(JsonNode request) {
List<Execution> list = service.listExecutions(request.path("stateMachineArn").asText());
ObjectNode response = objectMapper.createObjectNode();
diff --git a/src/main/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsService.java b/src/main/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsService.java
index b185dba2e8..fe7b03389b 100644
--- a/src/main/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsService.java
+++ b/src/main/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsService.java
@@ -16,6 +16,7 @@ import io.github.hectorvent.floci.services.stepfunctions.model.Activity;
import io.github.hectorvent.floci.services.stepfunctions.model.ActivityTask;
import io.github.hectorvent.floci.services.stepfunctions.model.Execution;
import io.github.hectorvent.floci.services.stepfunctions.model.HistoryEvent;
+import io.github.hectorvent.floci.services.stepfunctions.model.MapRun;
import io.github.hectorvent.floci.services.stepfunctions.model.MockedTestCase;
import io.github.hectorvent.floci.services.stepfunctions.model.StateMachine;
import io.github.hectorvent.floci.services.stepfunctions.model.StateMachineVersion;
@@ -44,6 +45,7 @@ public class StepFunctionsService implements Resettable, ResourceProvider {
private final StorageBackend<String, StateMachine> stateMachineStore;
private final StorageBackend<String, Execution> executionStore;
private final StorageBackend<String, Activity> activityStore;
+ private final StorageBackend<String, MapRun> mapRunStore;
private final Map<String, List<HistoryEvent>> historyCache = new ConcurrentHashMap<>();
private final Map<String, BlockingQueue<ActivityTask>> activityQueues = new ConcurrentHashMap<>();
private final Map<String, CompletableFuture<JsonNode>> pendingTaskTokens = new ConcurrentHashMap<>();
@@ -89,6 +91,8 @@ public class StepFunctionsService implements Resettable, ResourceProvider {
new TypeReference<Map<String, Execution>>() {});
this.activityStore = storageFactory.create("stepfunctions", "sfn-activities.json",
new TypeReference<Map<String, Activity>>() {});
+ this.mapRunStore = storageFactory.create("stepfunctions", "sfn-map-runs.json",
+ new TypeReference<Map<String, MapRun>>() {});
this.regionResolver = regionResolver;
this.aslExecutor = aslExecutor;
this.objectMapper = objectMapper;
@@ -777,6 +781,23 @@ public class StepFunctionsService implements Resettable, ResourceProvider {
LOG.debugv("Task heartbeat for token {0}", taskToken);
}
+ // ──────────────────────────── Map runs ────────────────────────────
+
+ /**
+ * Retains a finished Map run so {@code DescribeMapRun} can still report it once the execution
+ * that opened it is over. Reconciliation state machines read those counters from a later state,
+ * or from a later execution altogether, so the run has to outlive the Map that produced it.
+ */
+ public void recordMapRun(MapRun mapRun) {
+ mapRunStore.put(mapRun.getMapRunArn(), mapRun);
+ }
+
+ public MapRun describeMapRun(String mapRunArn) {
+ return mapRunStore.get(mapRunArn)
+ .orElseThrow(() -> new AwsException("ResourceNotFound",
+ "Resource not found: '" + mapRunArn + "'", 400));
+ }
+
// ──────────────────────────── Tags ────────────────────────────
public Map<String, String> listTags(String arn) {
diff --git a/src/main/java/io/github/hectorvent/floci/services/stepfunctions/model/MapRun.java b/src/main/java/io/github/hectorvent/floci/services/stepfunctions/model/MapRun.java
new file mode 100644
index 0000000000..9dc3e54cae
--- /dev/null
+++ b/src/main/java/io/github/hectorvent/floci/services/stepfunctions/model/MapRun.java
@@ -0,0 +1,44 @@
+package io.github.hectorvent.floci.services.stepfunctions.model;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import io.quarkus.runtime.annotations.RegisterForReflection;
+
+/**
+ * A distributed Map run that has finished, keyed by its Map run ARN.
+ *
+ * <p>A Map fails on the first item that fails, so a run only reaches the {@code ResultWriter} that
+ * mints its ARN once every item has succeeded. That is why a run carries a single {@code itemCount}
+ * rather than the ten counters {@code DescribeMapRun} reports: the other nine are zero, and
+ * {@code succeeded}, {@code total} and {@code resultsWritten} are all this count.
+ */
+@RegisterForReflection
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class MapRun {
+ private String mapRunArn;
+ /** The execution of the state machine whose Map state opened this run. */
+ private String executionArn;
+ private double startDate;
+ private double stopDate;
+ /** Items processed by the run, which is also the number of child executions it ran. */
+ private int itemCount;
+ /** The Map's declared MaxConcurrency, with an unbounded Map held as Integer.MAX_VALUE. */
+ private int maxConcurrency;
+
+ public String getMapRunArn() { return mapRunArn; }
+ public void setMapRunArn(String mapRunArn) { this.mapRunArn = mapRunArn; }
+
+ public String getExecutionArn() { return executionArn; }
+ public void setExecutionArn(String executionArn) { this.executionArn = executionArn; }
+
+ public double getStartDate() { return startDate; }
+ public void setStartDate(double startDate) { this.startDate = startDate; }
+
+ public double getStopDate() { return stopDate; }
+ public void setStopDate(double stopDate) { this.stopDate = stopDate; }
+
+ public int getItemCount() { return itemCount; }
+ public void setItemCount(int itemCount) { this.itemCount = itemCount; }
+
+ public int getMaxConcurrency() { return maxConcurrency; }
+ public void setMaxConcurrency(int maxConcurrency) { this.maxConcurrency = maxConcurrency; }
+}
diff --git a/src/test/java/io/github/hectorvent/floci/services/stepfunctions/AslExecutorResultWriterTest.java b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/AslExecutorResultWriterTest.java
index 4e7630eaf5..61abe6f70b 100644
--- a/src/test/java/io/github/hectorvent/floci/services/stepfunctions/AslExecutorResultWriterTest.java
+++ b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/AslExecutorResultWriterTest.java
@@ -54,6 +54,9 @@ class AslExecutorResultWriterTest {
s3Service = mock(S3Service.class);
when(s3Service.putObject(anyString(), anyString(), any(byte[].class), anyString(), any()))
.thenReturn(null);
+ // An exported Map run is retained through the service, so a Map state needs one to run.
+ Instance<StepFunctionsService> sfnService = mock(Instance.class);
+ when(sfnService.get()).thenReturn(mock(StepFunctionsService.class));
executor = new AslExecutor(
mock(LambdaExecutorService.class),
mock(LambdaFunctionStore.class),
@@ -70,7 +73,7 @@ class AslExecutorResultWriterTest {
mock(io.github.hectorvent.floci.services.scheduler.SchedulerController.class),
mapper,
new JsonataEvaluator(mapper),
- mock(Instance.class),
+ sfnService,
mock(EmulatorConfig.class),
null);
diff --git a/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsDescribeMapRunIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsDescribeMapRunIntegrationTest.java
new file mode 100644
index 0000000000..5baee890bf
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsDescribeMapRunIntegrationTest.java
@@ -0,0 +1,361 @@
+package io.github.hectorvent.floci.services.stepfunctions;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.github.hectorvent.floci.testing.RestAssuredJsonUtils;
+import io.quarkus.test.junit.QuarkusTest;
+import io.restassured.response.Response;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.MethodOrderer;
+import org.junit.jupiter.api.Order;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.TestMethodOrder;
+
+import static io.restassured.RestAssured.given;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.fail;
+
+/**
+ * Integration tests for {@code DescribeMapRun}, reached both directly through the API and through
+ * the {@code arn:aws:states:::aws-sdk:sfn:describeMapRun} Task integration.
+ *
+ * <p>Every asserted value was measured against us-east-1 with a distributed Map run of the same
+ * shape. A Map run only becomes describable once its {@code ResultWriter} has minted the Map run
+ * ARN and returned it in the Map result, which is also the only way an ASL author obtains it.
+ */
+@QuarkusTest
+@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
+class StepFunctionsDescribeMapRunIntegrationTest {
+
+ private static final String SFN_CONTENT_TYPE = "application/x-amz-json-1.0";
+ private static final String ROLE_ARN = "arn:aws:iam::000000000000:role/test-role";
+ private static final String ISO_INSTANT = "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z";
+ /** AWS reports an unbounded Map run as Integer.MAX_VALUE, not as the ASL default of 0. */
+ private static final int UNBOUNDED_CONCURRENCY = 2147483647;
+ private static final ObjectMapper mapper = new ObjectMapper();
+
+ private static String threeItemMapRunArn;
+ private static String threeItemExecutionArn;
+
+ @BeforeAll
+ static void configureRestAssured() {
+ RestAssuredJsonUtils.configureAwsContentTypes();
+ }
+
+ @Test
+ @Order(0)
+ void setup_runsADistributedMapOverThreeItems() throws Exception {
+ createBucket("describe-map-run");
+ var smArn = createStateMachine("describe-map-run-three", distributedMap(
+ "[{\"n\": 1}, {\"n\": 2}, {\"n\": 3}]", "describe-map-run", null));
+
+ threeItemExecutionArn = startExecution(smArn, "{}");
+ var describe = waitForTerminalState(threeItemExecutionArn);
+ assertEquals("SUCCEEDED", describe.jsonPath().getString("status"),
+ "cause: " + describe.jsonPath().getString("cause"));
+ threeItemMapRunArn = mapper.readTree(describe.jsonPath().getString("output"))
+ .path("MapRunArn").asText();
+ assertTrue(threeItemMapRunArn.contains(":mapRun:describe-map-run-three/"),
+ "unexpected MapRunArn: " + threeItemMapRunArn);
+ }
+
+ // ──────────────────────────── The API action ────────────────────────────
+
+ @Test
+ @Order(1)
+ void describeMapRunReportsTheRunItsParentExecutionAndItsWindow() {
+ var response = describeMapRun(threeItemMapRunArn);
+ response.then().statusCode(200);
+
+ assertEquals(threeItemMapRunArn, response.jsonPath().getString("mapRunArn"));
+ assertEquals(threeItemExecutionArn, response.jsonPath().getString("executionArn"));
+ assertEquals("SUCCEEDED", response.jsonPath().getString("status"));
+
+ // The wire response carries epoch seconds, as DescribeExecution does. The same instant in
+ // epoch milliseconds is three orders of magnitude larger, which the upper bound rules out.
+ double startDate = response.jsonPath().getDouble("startDate");
+ double stopDate = response.jsonPath().getDouble("stopDate");
+ assertTrue(startDate > 1.0e9 && startDate < 1.0e11,
+ "startDate is not an epoch second: " + startDate);
+ assertTrue(stopDate >= startDate && stopDate < 1.0e11,
+ "stopDate is not an epoch second at or after startDate: " + stopDate);
+ }
+
+ @Test
+ @Order(2)
+ void describeMapRunReportsAnUnboundedMapAsIntegerMaxValue() {
+ var response = describeMapRun(threeItemMapRunArn);
+ assertEquals(UNBOUNDED_CONCURRENCY, response.jsonPath().getInt("maxConcurrency"));
+ }
+
+ @Test
+ @Order(3)
+ void describeMapRunReportsZeroToleratedFailuresAndNoRedrive() {
+ var response = describeMapRun(threeItemMapRunArn);
+ assertEquals(0.0, response.jsonPath().getDouble("toleratedFailurePercentage"));
+ assertEquals(0, response.jsonPath().getInt("toleratedFailureCount"));
+ assertEquals(0, response.jsonPath().getInt("redriveCount"));
+ assertFalse(response.jsonPath().getMap("$").containsKey("redriveDate"),
+ "redriveDate is absent until a run is redriven");
+ }
+
+ @Test
+ @Order(4)
+ void describeMapRunCountsEveryItemAsSucceededAndWritten() {
+ var response = describeMapRun(threeItemMapRunArn);
+ assertCounters(response, "itemCounts", 3);
+ }
+
+ @Test
+ @Order(5)
+ void describeMapRunReportsOneChildExecutionPerItem() {
+ var response = describeMapRun(threeItemMapRunArn);
+ assertCounters(response, "executionCounts", 3);
+ }
+
+ @Test
+ @Order(6)
+ void describeMapRunCountsTheItemsOfThatRunRatherThanAFixedNumber() throws Exception {
+ createBucket("describe-map-run-five");
+ var smArn = createStateMachine("describe-map-run-five", distributedMap(
+ "[{\"n\": 1}, {\"n\": 2}, {\"n\": 3}, {\"n\": 4}, {\"n\": 5}]",
+ "describe-map-run-five", 2));
+
+ var describe = waitForTerminalState(startExecution(smArn, "{}"));
+ assertEquals("SUCCEEDED", describe.jsonPath().getString("status"),
+ "cause: " + describe.jsonPath().getString("cause"));
+ var mapRunArn = mapper.readTree(describe.jsonPath().getString("output"))
+ .path("MapRunArn").asText();
+
+ var response = describeMapRun(mapRunArn);
+ response.then().statusCode(200);
+ assertCounters(response, "itemCounts", 5);
+ assertCounters(response, "executionCounts", 5);
+ assertEquals(2, response.jsonPath().getInt("maxConcurrency"),
+ "an explicit MaxConcurrency is reported as declared");
+ }
+
+ @Test
+ @Order(7)
+ void describeMapRunOnAnUnknownArnReturnsResourceNotFound() {
+ var unknown = "arn:aws:states:us-east-1:000000000000:mapRun:describe-map-run-three/"
+ + "00000000-0000-0000-0000-000000000000:11111111-1111-1111-1111-111111111111";
+ var response = describeMapRun(unknown);
+
+ response.then().statusCode(400);
+ assertEquals("ResourceNotFound", response.jsonPath().getString("__type"));
+ assertEquals("Resource not found: '" + unknown + "'",
+ response.jsonPath().getString("message"));
+ }
+
+ // ──────────────────────────── The Task integration ────────────────────────────
+
+ @Test
+ @Order(8)
+ void describeMapRunTaskReturnsThePascalCaseResponseWithIsoDates() throws Exception {
+ var smArn = createStateMachine("describe-map-run-task", """
+ {
+ "QueryLanguage": "JSONata",
+ "StartAt": "Describe",
+ "States": {
+ "Describe": {
+ "Type": "Task",
+ "Resource": "arn:aws:states:::aws-sdk:sfn:describeMapRun",
+ "Arguments": {"MapRunArn": "MAP_RUN_ARN"},
+ "End": true
+ }
+ }
+ }
+ """.replace("MAP_RUN_ARN", threeItemMapRunArn));
+
+ var describe = waitForTerminalState(startExecution(smArn, "{}"));
+ assertEquals("SUCCEEDED", describe.jsonPath().getString("status"),
+ "cause: " + describe.jsonPath().getString("cause"));
+ var result = mapper.readTree(describe.jsonPath().getString("output"));
+
+ assertEquals(threeItemMapRunArn, result.path("MapRunArn").asText());
+ assertEquals(threeItemExecutionArn, result.path("ExecutionArn").asText());
+ assertEquals("SUCCEEDED", result.path("Status").asText());
+ assertEquals(UNBOUNDED_CONCURRENCY, result.path("MaxConcurrency").asInt());
+ assertEquals(0, result.path("ToleratedFailureCount").asInt());
+ assertEquals(0.0, result.path("ToleratedFailurePercentage").asDouble());
+ assertEquals(0, result.path("RedriveCount").asInt());
+ assertFalse(result.has("RedriveDate"), "RedriveDate is absent until a run is redriven");
+
+ // The aws-sdk: family renders a timestamp as the SDK's ISO-8601, not as epoch seconds.
+ assertTrue(result.path("StartDate").asText().matches(ISO_INSTANT),
+ "StartDate is not the SDK's ISO-8601 rendering: " + result.path("StartDate"));
+ assertTrue(result.path("StopDate").asText().matches(ISO_INSTANT),
+ "StopDate is not the SDK's ISO-8601 rendering: " + result.path("StopDate"));
+
+ assertTaskCounters(result.path("ItemCounts"), 3);
+ assertTaskCounters(result.path("ExecutionCounts"), 3);
+ }
+
+ @Test
+ @Order(9)
+ void describeMapRunTaskOnAnUnknownArnFailsWithTheSdkExceptionName() {
+ var unknown = "arn:aws:states:us-east-1:000000000000:mapRun:describe-map-run-three/"
+ + "00000000-0000-0000-0000-000000000000:22222222-2222-2222-2222-222222222222";
+ var smArn = createStateMachine("describe-map-run-task-unknown", """
+ {
+ "QueryLanguage": "JSONata",
+ "StartAt": "Describe",
+ "States": {
+ "Describe": {
+ "Type": "Task",
+ "Resource": "arn:aws:states:::aws-sdk:sfn:describeMapRun",
+ "Arguments": {"MapRunArn": "MAP_RUN_ARN"},
+ "End": true
+ }
+ }
+ }
+ """.replace("MAP_RUN_ARN", unknown));
+
+ var describe = waitForTerminalState(startExecution(smArn, "{}"));
+ assertEquals("FAILED", describe.jsonPath().getString("status"));
+ assertEquals("Sfn.ResourceNotFoundException", describe.jsonPath().getString("error"));
+ assertEquals("Resource not found: '" + unknown + "'",
+ describe.jsonPath().getString("cause"));
+ }
+
+ // ──────────────────────────── Helpers ────────────────────────────
+
+ /**
+ * The ten counters of a Map run all of whose items succeeded, as measured on us-east-1: every
+ * item is counted once under {@code succeeded}, {@code total} and {@code resultsWritten}.
+ */
+ private static void assertCounters(Response response, String set, int items) {
+ assertEquals(0, response.jsonPath().getInt(set + ".pending"));
+ assertEquals(0, response.jsonPath().getInt(set + ".running"));
+ assertEquals(items, response.jsonPath().getInt(set + ".succeeded"));
+ assertEquals(0, response.jsonPath().getInt(set + ".failed"));
+ assertEquals(0, response.jsonPath().getInt(set + ".timedOut"));
+ assertEquals(0, response.jsonPath().getInt(set + ".aborted"));
+ assertEquals(items, response.jsonPath().getInt(set + ".total"));
+ assertEquals(items, response.jsonPath().getInt(set + ".resultsWritten"));
+ assertEquals(0, response.jsonPath().getInt(set + ".failuresNotRedrivable"));
+ assertEquals(0, response.jsonPath().getInt(set + ".pendingRedrive"));
+ }
+
+ private static void assertTaskCounters(JsonNode counts, int items) {
+ assertEquals(0, counts.path("Pending").asInt());
+ assertEquals(0, counts.path("Running").asInt());
+ assertEquals(items, counts.path("Succeeded").asInt());
+ assertEquals(0, counts.path("Failed").asInt());
+ assertEquals(0, counts.path("TimedOut").asInt());
+ assertEquals(0, counts.path("Aborted").asInt());
+ assertEquals(items, counts.path("Total").asInt());
+ assertEquals(items, counts.path("ResultsWritten").asInt());
+ assertEquals(0, counts.path("FailuresNotRedrivable").asInt());
+ assertEquals(0, counts.path("PendingRedrive").asInt());
+ assertEquals(10, counts.size(), "a counter set carries exactly ten fields");
+ }
+
+ private static String distributedMap(String items, String bucket, Integer maxConcurrency) {
+ return """
+ {
+ "QueryLanguage": "JSONata",
+ "StartAt": "Fan",
+ "States": {
+ "Fan": {
+ "Type": "Map",
+ "End": true,
+ "Items": ITEMS,
+ CONCURRENCY
+ "ItemProcessor": {
+ "ProcessorConfig": {"Mode": "DISTRIBUTED", "ExecutionType": "STANDARD"},
+ "StartAt": "Keep",
+ "States": {"Keep": {"Type": "Pass", "End": true}}
+ },
+ "ResultWriter": {
+ "Resource": "arn:aws:states:::s3:putObject",
+ "Arguments": {"Bucket": "BUCKET", "Prefix": "out"}
+ }
+ }
+ }
+ }
+ """
+ .replace("ITEMS", items)
+ .replace("CONCURRENCY",
+ maxConcurrency == null ? "" : "\"MaxConcurrency\": " + maxConcurrency + ",")
+ .replace("BUCKET", bucket);
+ }
+
+ private static Response describeMapRun(String mapRunArn) {
+ return given()
+ .header("X-Amz-Target", "AWSStepFunctions.DescribeMapRun")
+ .contentType(SFN_CONTENT_TYPE)
+ .body("""
+ {"mapRunArn": "%s"}
+ """.formatted(mapRunArn))
+ .when().post("/");
+ }
+
+ private static void createBucket(String bucket) {
+ given().when().put("/" + bucket).then().statusCode(200);
+ }
+
+ private static String createStateMachine(String name, String definition) {
+ var resp = given()
+ .header("X-Amz-Target", "AWSStepFunctions.CreateStateMachine")
+ .contentType(SFN_CONTENT_TYPE)
+ .body("""
+ {"name": "%s", "roleArn": "%s", "definition": %s}
+ """.formatted(name, ROLE_ARN, quote(definition)))
+ .when().post("/");
+ resp.then().statusCode(200);
+ return resp.jsonPath().getString("stateMachineArn");
+ }
+
+ private static String startExecution(String smArn, String input) {
+ var resp = given()
+ .header("X-Amz-Target", "AWSStepFunctions.StartExecution")
+ .contentType(SFN_CONTENT_TYPE)
+ .body("""
+ {"stateMachineArn": "%s", "input": %s}
+ """.formatted(smArn, quote(input)))
+ .when().post("/");
+ resp.then().statusCode(200);
+ return resp.jsonPath().getString("executionArn");
+ }
+
+ private static Response describeExecution(String execArn) {
+ return given()
+ .header("X-Amz-Target", "AWSStepFunctions.DescribeExecution")
+ .contentType(SFN_CONTENT_TYPE)
+ .body("""
+ {"executionArn": "%s"}
+ """.formatted(execArn))
+ .when().post("/");
+ }
+
+ private static Response waitForTerminalState(String execArn) {
+ for (var i = 0; i < 150; i++) {
+ var resp = describeExecution(execArn);
+ if (!"RUNNING".equals(resp.jsonPath().getString("status"))) {
+ return resp;
+ }
+ try {
+ Thread.sleep(100);
+ } catch (InterruptedException e) {
+ Thread.currentThread().interrupt();
+ fail("Interrupted while waiting for execution " + execArn);
+ }
+ }
+ fail("Execution did not complete within timeout: " + execArn);
+ return null;
+ }
+
+ private static String quote(String raw) {
+ return "\"" + raw
+ .replace("\\", "\\\\")
+ .replace("\"", "\\\"")
+ .replace("\n", "\\n")
+ .replace("\r", "\\r")
+ .replace("\t", "\\t")
+ + "\"";
+ }
+}