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.javanew file mode 100644index 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.mdindex 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.javaindex 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.javaindex 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.javaindex 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.javanew file mode 100644index 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.javaindex 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.javanew file mode 100644index 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")+ + "\"";+ }+}