Skip to content

armgit / floci

Public Imported from GitHub
0

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

fix(stepfunctions): paginate ListExecutions (#6727)

Jimmy Liu Jiaa8151ff56b8c
diff --git a/src/main/java/io/github/hectorvent/floci/core/common/Pagination.java b/src/main/java/io/github/hectorvent/floci/core/common/Pagination.java
index af83141945..ae2b534ea2 100644
--- a/src/main/java/io/github/hectorvent/floci/core/common/Pagination.java
+++ b/src/main/java/io/github/hectorvent/floci/core/common/Pagination.java
@@ -2,9 +2,12 @@ package io.github.hectorvent.floci.core.common;
import com.fasterxml.jackson.databind.JsonNode;
+import java.time.Clock;
+import java.time.Duration;
import java.util.Comparator;
import java.util.List;
import java.util.function.Function;
+import java.util.function.Supplier;
import java.util.stream.Collectors;
/**
@@ -75,6 +78,33 @@ public final class Pagination {
prefix, Pagination::encodeToken);
}
+ /** Paginates namespaced cursors that are invalid after the supplied lifetime. */
+ public static <T> PaginatedResult<T> paginateExpiring(List<T> all, Function<T, String> cursorOf,
+ int limit, String nextToken, String namespace,
+ Clock clock, Duration lifetime, SignedMarkers markers,
+ Function<String, AwsException> invalidToken) {
+ return paginateExpiring(() -> all, cursorOf, limit, nextToken, namespace, clock, lifetime,
+ markers, invalidToken);
+ }
+
+ /** Decodes the token before loading items whose lookup can fail independently. */
+ public static <T> PaginatedResult<T> paginateExpiring(Supplier<List<T>> all, Function<T, String> cursorOf,
+ int limit, String nextToken, String namespace,
+ Clock clock, Duration lifetime, SignedMarkers markers,
+ Function<String, AwsException> invalidToken) {
+ if (limit < 1) {
+ throw new IllegalArgumentException("limit must be at least 1, was " + limit);
+ }
+ if (lifetime.isNegative()) {
+ throw new IllegalArgumentException("lifetime must not be negative, was " + lifetime);
+ }
+ String prefix = namespace + ":";
+ long nowMillis = clock.millis();
+ String after = decodeExpiringCursor(nextToken, prefix, nowMillis, lifetime.toMillis(), markers, invalidToken);
+ String tokenPrefix = prefix + nowMillis + ":";
+ return slice(all.get(), cursorOf, limit, after, tokenPrefix, markers::issue);
+ }
+
/** Paginates with instance-signed markers, optionally scoped by a prefix within the signed cursor. */
public static <T> PaginatedResult<T> paginate(List<T> all, Function<T, String> cursorOf,
int limit, String marker, SignedMarkers markers,
@@ -197,6 +227,26 @@ public final class Pagination {
return decoded.substring(prefix.length());
}
+ private static String decodeExpiringCursor(String token, String prefix, long nowMillis,
+ long lifetimeMillis, SignedMarkers markers,
+ Function<String, AwsException> invalidToken) {
+ if (token == null || token.isEmpty()) {
+ return null;
+ }
+ String decoded = markers.cursorOf(token);
+ if (decoded == null || !decoded.startsWith(prefix)) {
+ throw invalidToken.apply(token);
+ }
+ String issuedAndCursor = decoded.substring(prefix.length());
+ int separator = issuedAndCursor.indexOf(':');
+ long issuedMillis = Long.parseLong(issuedAndCursor.substring(0, separator));
+ long ageMillis = nowMillis - issuedMillis;
+ if (issuedMillis > nowMillis || ageMillis > lifetimeMillis) {
+ throw invalidToken.apply(token);
+ }
+ return issuedAndCursor.substring(separator + 1);
+ }
+
private static String decodeToken(String token) {
if (token == null || token.isEmpty()) {
return null;
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 393d7273dd..c44050aded 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
@@ -8,6 +8,7 @@ import io.github.hectorvent.floci.core.common.AwsErrorResponse;
import io.github.hectorvent.floci.core.common.AwsException;
import io.github.hectorvent.floci.core.common.Digests;
import io.github.hectorvent.floci.core.common.PaginatedResult;
+import io.github.hectorvent.floci.core.common.Pagination;
import io.github.hectorvent.floci.core.common.SignedMarkers;
import io.github.hectorvent.floci.core.common.SmithyValidationErrors;
import io.github.hectorvent.floci.services.stepfunctions.model.Activity;
@@ -26,7 +27,6 @@ import jakarta.ws.rs.core.Response;
import java.time.Clock;
import java.time.Duration;
import java.util.ArrayList;
-import java.util.Collections;
import java.util.HashMap;
import java.util.LinkedHashMap;
import java.util.List;
@@ -482,14 +482,15 @@ public class StepFunctionsJsonHandler {
throw new AwsException("ValidationException",
"PENDING_REDRIVE execution listing is not supported.", 400);
}
- List<Execution> list = service.listExecutions(request.path("stateMachineArn").asText());
+ String stateMachineArn = request.path("stateMachineArn").asText();
+ Integer maxResults = parseOptionalInt(request, "maxResults");
+ String nextToken = optionalText(request, "nextToken");
+ PaginatedResult<StepFunctionsService.ExecutionSnapshot> page = service.listExecutions(
+ stateMachineArn, statusFilter, maxResults, nextToken);
ObjectNode response = objectMapper.createObjectNode();
ArrayNode array = response.putArray("executions");
- for (Execution e : list) {
- String status = e.getStatus();
- if (statusFilter != null && !statusFilter.equals(status)) {
- continue;
- }
+ for (StepFunctionsService.ExecutionSnapshot snapshot : page.items()) {
+ Execution e = snapshot.execution();
ObjectNode item = array.addObject();
item.put("executionArn", e.getExecutionArn());
item.put("stateMachineArn", e.getStateMachineArn());
@@ -500,10 +501,13 @@ public class StepFunctionsJsonHandler {
item.put("stateMachineAliasArn", e.getStateMachineAliasArn());
}
item.put("name", e.getName());
- item.put("status", status);
+ item.put("status", snapshot.status());
item.put("startDate", e.getStartDate());
if (e.getStopDate() != null) item.put("stopDate", e.getStopDate());
}
+ if (page.nextToken() != null) {
+ response.put("nextToken", page.nextToken());
+ }
return Response.ok(response).build();
}
@@ -525,28 +529,20 @@ public class StepFunctionsJsonHandler {
Integer maxResults = parseOptionalInt(request, "maxResults");
String nextToken = optionalText(request, "nextToken");
int pageSize = StepFunctionsPaging.pageSize(maxResults, nextToken);
- Long lastReturnedId = nextToken == null ? null : historyTokenPosition(nextToken, arn, reverseOrder);
- List<HistoryEvent> live = service.getExecutionHistory(arn);
- List<HistoryEvent> events;
- // Branch and iteration threads append under the history's own monitor while a client reads.
- synchronized (live) {
- events = new ArrayList<>(live);
- }
- if (reverseOrder) {
- Collections.reverse(events);
- }
- // Ids rise in the order events were recorded, so a page starts at the first event listed
- // after the last one the previous page returned, however many were recorded in between.
- int start = 0;
- while (lastReturnedId != null && start < events.size()
- && !listedAfter(events.get(start), lastReturnedId, reverseOrder)) {
- start++;
- }
- int end = Math.min(events.size(), start + pageSize);
+ PaginatedResult<HistoryEvent> page = Pagination.paginateExpiring(() -> {
+ List<HistoryEvent> live = service.getExecutionHistory(arn);
+ // Branch and iteration threads append under the history's own monitor while a client reads.
+ synchronized (live) {
+ return new ArrayList<>(live);
+ }
+ },
+ event -> historyEventCursor(event, reverseOrder), pageSize, nextToken,
+ historyTokenScope(arn, reverseOrder), clock, HISTORY_TOKEN_LIFETIME, historyTokens,
+ token -> invalidHistoryToken());
ObjectNode response = objectMapper.createObjectNode();
ArrayNode array = response.putArray("events");
- for (HistoryEvent e : events.subList(start, end)) {
+ for (HistoryEvent e : page.items()) {
ObjectNode item = array.addObject();
item.put("id", e.getId());
item.put("timestamp", e.getTimestamp());
@@ -562,39 +558,15 @@ public class StepFunctionsJsonHandler {
item.set(historyEventDetailsField(e.getType()), objectMapper.valueToTree(details));
}
}
- if (end < events.size()) {
- response.put("nextToken", issueHistoryToken(arn, reverseOrder, events.get(end - 1).getId()));
+ if (page.nextToken() != null) {
+ response.put("nextToken", page.nextToken());
}
return Response.ok(response).build();
}
- private static boolean listedAfter(HistoryEvent event, long id, boolean reverseOrder) {
- return reverseOrder ? event.getId() < id : event.getId() > id;
- }
-
- /**
- * A history token names its execution, its order and the last event its page returned, and
- * may be used with any page size and includeExecutionData. The execution is named by the
- * SHA-256 of its ARN, so the token stays far below the 1,024 characters AWS allows however long
- * the ARN is. Tokens are signed, so an edited one, or one issued before a restart, is refused,
- * and each expires 24 hours after it was issued, as on AWS.
- */
- private String issueHistoryToken(String arn, boolean reverseOrder, long lastReturnedId) {
- return historyTokens.issue(
- clock.millis() + ":" + historyTokenScope(arn, reverseOrder) + ":" + lastReturnedId);
- }
-
- private long historyTokenPosition(String nextToken, String arn, boolean reverseOrder) {
- String issued = historyTokens.cursorOf(nextToken);
- if (issued == null) {
- throw invalidHistoryToken();
- }
- String[] fields = issued.split(":");
- if (!fields[1].equals(historyTokenScope(arn, reverseOrder))
- || clock.millis() - Long.parseLong(fields[0]) > HISTORY_TOKEN_LIFETIME.toMillis()) {
- throw invalidHistoryToken();
- }
- return Long.parseLong(fields[2]);
+ private static String historyEventCursor(HistoryEvent event, boolean reverseOrder) {
+ long position = reverseOrder ? Long.MAX_VALUE - event.getId() : event.getId();
+ return String.format("%019d", position);
}
private static String historyTokenScope(String arn, boolean reverseOrder) {
diff --git a/src/main/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsPaging.java b/src/main/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsPaging.java
index 09a76aac0c..1b6c452a2e 100644
--- a/src/main/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsPaging.java
+++ b/src/main/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsPaging.java
@@ -3,9 +3,11 @@ package io.github.hectorvent.floci.services.stepfunctions;
import io.github.hectorvent.floci.core.common.AwsException;
/**
- * The page request ListActivities, ListStateMachines and GetExecutionHistory check: a {@code maxResults} of 0 to 1000,
- * where 0 or none means 100, and a {@code nextToken} of 1 to 1024 characters. Callers read both
- * fields before calling it, so a wrongly typed field is reported before either bound.
+ * The page requests ListActivities, ListStateMachines, GetExecutionHistory, and ListExecutions
+ * check a {@code maxResults} of 0 to 1000, where 0 or none means 100. ListActivities,
+ * ListStateMachines, and GetExecutionHistory accept a {@code nextToken} of 1 to 1024 characters;
+ * ListExecutions accepts up to 3096 characters. Callers read both fields before calling it, so a
+ * wrongly typed field is reported before either bound.
*/
final class StepFunctionsPaging {
@@ -18,11 +20,17 @@ final class StepFunctionsPaging {
/** Validates the pair and returns the number of items a page holds. */
static int pageSize(Integer maxResults, String nextToken) {
+ return pageSize(maxResults, nextToken, MAX_TOKEN_LENGTH);
+ }
+
+ /** Validates the pair using the operation's modeled token length. */
+ static int pageSize(Integer maxResults, String nextToken, int maxTokenLength) {
if (maxResults != null && (maxResults < 0 || maxResults > MAX_PAGE_SIZE)) {
throw new AwsException("ValidationException", "maxResults must be between 0 and 1000.", 400);
}
- if (nextToken != null && (nextToken.isEmpty() || nextToken.length() > MAX_TOKEN_LENGTH)) {
- throw new AwsException("ValidationException", "nextToken length must be between 1 and 1024.", 400);
+ if (nextToken != null && (nextToken.isEmpty() || nextToken.length() > maxTokenLength)) {
+ throw new AwsException("ValidationException",
+ "nextToken length must be between 1 and " + maxTokenLength + ".", 400);
}
return maxResults == null || maxResults == 0 ? DEFAULT_PAGE_SIZE : maxResults;
}
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 6a80985d85..14ff67883f 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
@@ -9,10 +9,13 @@ import io.github.hectorvent.floci.core.common.AwsArnShapes;
import io.github.hectorvent.floci.core.common.AwsArnUtils;
import io.github.hectorvent.floci.core.common.AwsException;
import io.github.hectorvent.floci.core.common.AwsRegions;
+import io.github.hectorvent.floci.core.common.Base64Url;
+import io.github.hectorvent.floci.core.common.Digests;
import io.github.hectorvent.floci.core.common.PaginatedResult;
import io.github.hectorvent.floci.core.common.Pagination;
import io.github.hectorvent.floci.core.common.RegionResolver;
import io.github.hectorvent.floci.core.common.Resettable;
+import io.github.hectorvent.floci.core.common.SignedMarkers;
import io.github.hectorvent.floci.core.resource.ExplorerResource;
import io.github.hectorvent.floci.core.resource.ResourceProvider;
import io.github.hectorvent.floci.core.resource.SupportedResourceType;
@@ -34,6 +37,9 @@ import jakarta.inject.Inject;
import org.jboss.logging.Logger;
import java.math.BigDecimal;
+import java.nio.charset.StandardCharsets;
+import java.time.Clock;
+import java.time.Duration;
import java.time.Instant;
import java.time.ZoneOffset;
import java.time.format.DateTimeFormatter;
@@ -50,9 +56,11 @@ import java.util.regex.Pattern;
@ApplicationScoped
public class StepFunctionsService implements Resettable, ResourceProvider {
+ private static final int LIST_EXECUTIONS_MAX_TOKEN_LENGTH = 3096;
private static final Logger LOG = Logger.getLogger(StepFunctionsService.class);
private static final int HISTORY_PERSIST_CHECKPOINT = 100;
+ private static final Duration LIST_EXECUTIONS_TOKEN_LIFETIME = Duration.ofHours(24);
private final StorageBackend<String, StateMachine> stateMachineStore;
private final StorageBackend<String, StateMachineAlias> stateMachineAliasStore;
@@ -102,6 +110,8 @@ public class StepFunctionsService implements Resettable, ResourceProvider {
private final ObjectMapper objectMapper;
private final SfnMockLoader mockLoader;
private final StepFunctionsEventPublisher eventPublisher;
+ private final Clock clock;
+ private final SignedMarkers listExecutionTokens = new SignedMarkers();
// Fields that are valid only in JSONPath mode. Validated against real AWS:
// creating a JSONata state machine with any of these fields returns SCHEMA_VALIDATION_FAILED.
@@ -151,10 +161,18 @@ public class StepFunctionsService implements Resettable, ResourceProvider {
new FieldStateTypeRule("Catch", Set.of("Task", "Parallel", "Map")),
new FieldStateTypeRule("Retry", Set.of("Task", "Parallel", "Map")));
- @Inject
public StepFunctionsService(StorageFactory storageFactory, RegionResolver regionResolver,
AslExecutor aslExecutor, ObjectMapper objectMapper,
SfnMockLoader mockLoader, StepFunctionsEventPublisher eventPublisher) {
+ this(storageFactory, regionResolver, aslExecutor, objectMapper, mockLoader, eventPublisher,
+ Clock.systemUTC());
+ }
+
+ @Inject
+ public StepFunctionsService(StorageFactory storageFactory, RegionResolver regionResolver,
+ AslExecutor aslExecutor, ObjectMapper objectMapper,
+ SfnMockLoader mockLoader, StepFunctionsEventPublisher eventPublisher,
+ Clock clock) {
this.stateMachineStore = storageFactory.create("stepfunctions", "sfn-state-machines.json",
new TypeReference<Map<String, StateMachine>>() {});
this.executionStore = storageFactory.create("stepfunctions", "sfn-executions.json",
@@ -173,6 +191,7 @@ public class StepFunctionsService implements Resettable, ResourceProvider {
this.objectMapper = objectMapper;
this.mockLoader = mockLoader;
this.eventPublisher = eventPublisher;
+ this.clock = clock;
}
public void clear() {
@@ -1019,6 +1038,36 @@ public class StepFunctionsService implements Resettable, ResourceProvider {
}).orElse(false));
}
+ /** Returns a filtered, newest-first page of executions for the ListExecutions API. */
+ public PaginatedResult<ExecutionSnapshot> listExecutions(String stateMachineArn, String statusFilter,
+ Integer maxResults, String nextToken) {
+ int pageSize = StepFunctionsPaging.pageSize(maxResults, nextToken, LIST_EXECUTIONS_MAX_TOKEN_LENGTH);
+ List<ExecutionSnapshot> matching = listExecutions(stateMachineArn).stream()
+ .map(execution -> new ExecutionSnapshot(execution, execution.getStatus()))
+ .filter(snapshot -> statusFilter == null || statusFilter.equals(snapshot.status()))
+ .toList();
+ String scope = "states:executions:" + regionResolver.getAccountId() + ":" + stateMachineArn + ":"
+ + (statusFilter == null ? "*" : statusFilter);
+ String namespace = "states:executions:" + Base64Url.encode(
+ Digests.sha256(scope.getBytes(StandardCharsets.UTF_8)));
+ return Pagination.paginateExpiring(matching, StepFunctionsService::executionPaginationCursor,
+ pageSize, nextToken, namespace, clock, LIST_EXECUTIONS_TOKEN_LIFETIME, listExecutionTokens,
+ token -> new AwsException("InvalidToken", "Invalid nextToken.", 400));
+ }
+
+ public record ExecutionSnapshot(Execution execution, String status) {
+ }
+
+ /** Sorts newest executions first while keeping equal timestamps deterministic. */
+ private static String executionPaginationCursor(ExecutionSnapshot snapshot) {
+ Execution execution = snapshot.execution();
+ Double stopDate = execution.getStopDate();
+ double sortDate = "RUNNING".equals(snapshot.status()) || stopDate == null
+ ? execution.getStartDate() : stopDate;
+ long sortMillis = Math.round(sortDate * 1000.0);
+ return String.format("%019d:%s", Long.MAX_VALUE - sortMillis, execution.getExecutionArn());
+ }
+
/**
* Aborts a running execution. The caller's {@code error} and {@code cause} land on the
* Execution itself, not only on the history event, so DescribeExecution reports them.
diff --git a/src/test/java/io/github/hectorvent/floci/core/common/PaginationTest.java b/src/test/java/io/github/hectorvent/floci/core/common/PaginationTest.java
index 86a8344ef3..230f82f366 100644
--- a/src/test/java/io/github/hectorvent/floci/core/common/PaginationTest.java
+++ b/src/test/java/io/github/hectorvent/floci/core/common/PaginationTest.java
@@ -5,6 +5,8 @@ import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.function.Executable;
import java.nio.charset.StandardCharsets;
+import java.time.Clock;
+import java.time.Duration;
import java.util.Base64;
import java.util.List;
import java.util.function.Function;
@@ -95,6 +97,22 @@ class PaginationTest {
() -> signedPage(markers, 1, "!!!", "")));
}
+ @Test
+ void expiringPaging_validatesTheTokenBeforeLoadingItems() {
+ SignedMarkers markers = new SignedMarkers();
+ Clock clock = Clock.systemUTC();
+ Duration lifetime = Duration.ofDays(1);
+
+ assertSame(INVALID, assertThrows(AwsException.class,
+ () -> Pagination.paginateExpiring(() -> {
+ throw new AssertionError("items loaded before token validation");
+ }, Function.identity(), 1, "not-a-token", "scope", clock, lifetime, markers, INVALID_TOKEN)));
+
+ PaginatedResult<String> first = Pagination.paginateExpiring(() -> ITEMS, Function.identity(),
+ 1, null, "scope", clock, lifetime, markers, INVALID_TOKEN);
+ assertThat(first.items(), contains("a"));
+ }
+
@Test
void paging_aLimitNearIntMaxDoesNotReportAFurtherPage() {
String afterFirst = page(1, null, "ns").nextToken();
diff --git a/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsExecutionHistoryTokenTest.java b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsExecutionHistoryTokenTest.java
index 58f03aa9a9..150a96c8de 100644
--- a/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsExecutionHistoryTokenTest.java
+++ b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsExecutionHistoryTokenTest.java
@@ -69,6 +69,14 @@ class StepFunctionsExecutionHistoryTokenTest {
assertInvalid(new StepFunctionsJsonHandler(service, mapper, clock), token);
}
+ @Test
+ void aTokenIssuedAfterTheCurrentTimeIsRefused() {
+ String token = firstPageToken();
+
+ when(clock.millis()).thenReturn(ISSUED - 1);
+ assertInvalid(handler, token);
+ }
+
@Test
void aTokenWhoseIssueTimeWasMovedForwardIsRefused() {
String token = firstPageToken();
diff --git a/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsListExecutionsFilterTest.java b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsListExecutionsFilterTest.java
index 1b3eff67f4..67e7765a66 100644
--- a/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsListExecutionsFilterTest.java
+++ b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsListExecutionsFilterTest.java
@@ -4,6 +4,7 @@ import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import io.github.hectorvent.floci.core.common.AwsException;
+import io.github.hectorvent.floci.core.common.PaginatedResult;
import io.github.hectorvent.floci.services.stepfunctions.model.Execution;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
@@ -15,6 +16,8 @@ import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.nullable;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.verifyNoInteractions;
import static org.mockito.Mockito.when;
@@ -30,16 +33,23 @@ class StepFunctionsListExecutionsFilterTest {
void setUp() {
service = mock(StepFunctionsService.class);
handler = new StepFunctionsJsonHandler(service, mapper, Clock.systemUTC());
- when(service.listExecutions(ARN)).thenReturn(
- List.of("RUNNING", "SUCCEEDED", "FAILED", "TIMED_OUT", "ABORTED").stream()
- .map(status -> {
- Execution execution = new Execution();
- execution.setExecutionArn(ARN + ":" + status);
- execution.setStateMachineArn(ARN);
- execution.setName(status);
- execution.setStatus(status);
- return execution;
- }).toList());
+ List<StepFunctionsService.ExecutionSnapshot> executions = List.of(
+ "RUNNING", "SUCCEEDED", "FAILED", "TIMED_OUT", "ABORTED").stream()
+ .map(status -> {
+ Execution execution = new Execution();
+ execution.setExecutionArn(ARN + ":" + status);
+ execution.setStateMachineArn(ARN);
+ execution.setName(status);
+ execution.setStatus(status);
+ return new StepFunctionsService.ExecutionSnapshot(execution, status);
+ }).toList();
+ when(service.listExecutions(eq(ARN), nullable(String.class), nullable(Integer.class), nullable(String.class)))
+ .thenAnswer(invocation -> {
+ String status = invocation.getArgument(1);
+ List<StepFunctionsService.ExecutionSnapshot> page = status == null ? executions : executions.stream()
+ .filter(snapshot -> status.equals(snapshot.status())).toList();
+ return new PaginatedResult<>(page, null);
+ });
}
@ParameterizedTest
@@ -59,17 +69,17 @@ class StepFunctionsListExecutionsFilterTest {
@Test
void absentMatchesReturnAnEmptyArray() {
- Execution succeeded = new Execution();
- succeeded.setStatus("SUCCEEDED");
- when(service.listExecutions(ARN)).thenReturn(List.of(succeeded));
+ when(service.listExecutions(ARN, "RUNNING", null, null)).thenReturn(
+ new PaginatedResult<>(List.of(), null));
assertEquals(0, list(request().put("statusFilter", "RUNNING")).size());
}
@Test
void emittedStatusIsTheSameSnapshotThatMatchedTheFilter() {
Execution execution = mock(Execution.class);
- when(execution.getStatus()).thenReturn("RUNNING", "SUCCEEDED");
- when(service.listExecutions(ARN)).thenReturn(List.of(execution));
+ when(service.listExecutions(ARN, "RUNNING", null, null)).thenReturn(
+ new PaginatedResult<>(List.of(
+ new StepFunctionsService.ExecutionSnapshot(execution, "RUNNING")), null));
JsonNode executions = list(request().put("statusFilter", "RUNNING"));
assertEquals(1, executions.size());
assertEquals("RUNNING", executions.get(0).path("status").asText());
diff --git a/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsListExecutionsPaginationTest.java b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsListExecutionsPaginationTest.java
new file mode 100644
index 0000000000..abd0072989
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsListExecutionsPaginationTest.java
@@ -0,0 +1,76 @@
+package io.github.hectorvent.floci.services.stepfunctions;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import io.github.hectorvent.floci.core.common.PaginatedResult;
+import io.github.hectorvent.floci.services.stepfunctions.model.Execution;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.time.Clock;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+class StepFunctionsListExecutionsPaginationTest {
+
+ private static final String ARN = "arn:aws:states:us-east-1:000000000000:stateMachine:pagination";
+
+ private final ObjectMapper mapper = new ObjectMapper();
+ private StepFunctionsService service;
+ private StepFunctionsJsonHandler handler;
+
+ @BeforeEach
+ void setUp() {
+ service = mock(StepFunctionsService.class);
+ handler = new StepFunctionsJsonHandler(service, mapper, Clock.systemUTC());
+
+ Execution newer = execution("newer", 2.0);
+ when(service.listExecutions(ARN, null, 1, null)).thenReturn(
+ new PaginatedResult<>(List.of(
+ new StepFunctionsService.ExecutionSnapshot(newer, "SUCCEEDED")), "continuation"));
+ }
+
+ @Test
+ void maxResultsCapsThePageAndReturnsAContinuationToken() {
+ ObjectNode request = mapper.createObjectNode()
+ .put("stateMachineArn", ARN)
+ .put("maxResults", 1);
+
+ JsonNode response = (JsonNode) handler.handle("ListExecutions", request, "us-east-1").getEntity();
+
+ assertEquals(1, response.path("executions").size());
+ assertEquals("newer", response.path("executions").get(0).path("name").asText());
+ assertNotNull(response.path("nextToken").textValue());
+ }
+
+ @Test
+ void omitsNextTokenWhenTheServiceReturnsTheFinalPage() {
+ when(service.listExecutions(ARN, "SUCCEEDED", null, "continuation"))
+ .thenReturn(new PaginatedResult<>(List.of(), null));
+ ObjectNode request = mapper.createObjectNode()
+ .put("stateMachineArn", ARN)
+ .put("statusFilter", "SUCCEEDED")
+ .put("nextToken", "continuation");
+
+ JsonNode response = (JsonNode) handler.handle("ListExecutions", request, "us-east-1").getEntity();
+
+ assertEquals(0, response.path("executions").size());
+ assertFalse(response.has("nextToken"));
+ }
+
+ private static Execution execution(String name, double startDate) {
+ Execution execution = new Execution();
+ execution.setExecutionArn(ARN + ":" + name);
+ execution.setStateMachineArn(ARN);
+ execution.setName(name);
+ execution.setStatus("SUCCEEDED");
+ execution.setStartDate(startDate);
+ return execution;
+ }
+}
diff --git a/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsListExecutionsServiceTest.java b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsListExecutionsServiceTest.java
new file mode 100644
index 0000000000..facb19ca4c
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsListExecutionsServiceTest.java
@@ -0,0 +1,310 @@
+package io.github.hectorvent.floci.services.stepfunctions;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import io.github.hectorvent.floci.core.common.AwsException;
+import io.github.hectorvent.floci.core.common.Base64Url;
+import io.github.hectorvent.floci.core.common.Digests;
+import io.github.hectorvent.floci.core.common.PaginatedResult;
+import io.github.hectorvent.floci.core.common.RegionResolver;
+import io.github.hectorvent.floci.core.storage.AccountAwareStorageBackend;
+import io.github.hectorvent.floci.core.storage.StorageFactory;
+import io.github.hectorvent.floci.services.stepfunctions.model.Activity;
+import io.github.hectorvent.floci.services.stepfunctions.model.Execution;
+import io.github.hectorvent.floci.services.stepfunctions.model.MapRun;
+import io.github.hectorvent.floci.services.stepfunctions.model.StateMachine;
+import io.github.hectorvent.floci.services.stepfunctions.model.StateMachineAlias;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.nio.charset.StandardCharsets;
+import java.time.Clock;
+import java.time.Duration;
+import java.time.Instant;
+import java.time.ZoneId;
+import java.time.ZoneOffset;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.doReturn;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.spy;
+import static org.mockito.Mockito.when;
+
+class StepFunctionsListExecutionsServiceTest {
+
+ private static final String ACCOUNT = "000000000000";
+ private static final String ARN = "arn:aws:states:us-east-1:" + ACCOUNT + ":stateMachine:pages";
+ private static final Instant TOKEN_TIME = Instant.parse("2026-01-01T00:00:00Z");
+
+ private AccountAwareStorageBackend<Execution> executionStore;
+ private MutableClock clock;
+ private StepFunctionsService service;
+
+ @BeforeEach
+ void setUp() {
+ StorageFactory factory = mock(StorageFactory.class);
+ executionStore = spy(AccountAwareStorageBackend.inMemory(ACCOUNT));
+ clock = new MutableClock(TOKEN_TIME);
+ doReturn(AccountAwareStorageBackend.<StateMachine>inMemory(ACCOUNT))
+ .doReturn(executionStore)
+ .doReturn(AccountAwareStorageBackend.<Activity>inMemory(ACCOUNT))
+ .doReturn(AccountAwareStorageBackend.<MapRun>inMemory(ACCOUNT))
+ .doReturn(AccountAwareStorageBackend.<StateMachineAlias>inMemory(ACCOUNT))
+ .when(factory).create(anyString(), anyString(), any());
+ service = new StepFunctionsService(factory, new RegionResolver("us-east-1", ACCOUNT), null,
+ new ObjectMapper(), mock(SfnMockLoader.class), mock(StepFunctionsEventPublisher.class), clock);
+
+ put("new", 3.0, "SUCCEEDED");
+ put("running", 2.0, "RUNNING");
+ put("old", 1.0, "SUCCEEDED");
+ }
+
+ @Test
+ void pagesNewestExecutionsAndResumesFromTheOpaqueToken() {
+ PaginatedResult<StepFunctionsService.ExecutionSnapshot> first = service.listExecutions(ARN, null, 1, null);
+ assertEquals(List.of("new"), first.items().stream().map(snapshot -> snapshot.execution().getName()).toList());
+ assertNotNull(first.nextToken());
+
+ PaginatedResult<StepFunctionsService.ExecutionSnapshot> second = service.listExecutions(
+ ARN, null, 1, first.nextToken());
+ assertEquals(List.of("running"), second.items().stream().map(snapshot -> snapshot.execution().getName())
+ .toList());
+ assertNotNull(second.nextToken());
+ }
+
+ @Test
+ void continuationTokenCarriesItsIssueTimeForExpiryValidation() {
+ String token = service.listExecutions(ARN, null, 1, null).nextToken();
+
+ String payload = Base64Url.decode(token);
+ String scope = "states:executions:" + ACCOUNT + ":" + ARN + ":*";
+ String namespace = "states:executions:" + Base64Url.encode(
+ Digests.sha256(scope.getBytes(StandardCharsets.UTF_8)));
+ assertTrue(payload.startsWith(namespace + ":"), payload);
+ assertTrue(payload.substring(namespace.length() + 1)
+ .matches("\\d+:\\d{19}:.*\\.[A-Za-z0-9_-]{43}"), payload);
+ }
+
+ @Test
+ void continuationTokenExpiresAfterTwentyFourHours() {
+ String token = service.listExecutions(ARN, null, 1, null).nextToken();
+
+ clock.advance(Duration.ofHours(24));
+ PaginatedResult<StepFunctionsService.ExecutionSnapshot> atBoundary = service.listExecutions(
+ ARN, null, 1, token);
+ assertEquals(List.of("running"), atBoundary.items().stream()
+ .map(snapshot -> snapshot.execution().getName()).toList());
+
+ clock.advance(Duration.ofMillis(1));
+ AwsException error = assertThrows(AwsException.class,
+ () -> service.listExecutions(ARN, null, 1, token));
+ assertEquals("InvalidToken", error.getErrorCode());
+ }
+
+ @Test
+ void longUnicodeNamesStillProduceAUsableTokenWithinTheAwsLengthLimit() {
+ String stateMachineName = "界".repeat(80);
+ String longArn = "arn:aws:states:us-east-1:" + ACCOUNT + ":stateMachine:" + stateMachineName;
+ Execution later = execution(longArn, "a".repeat(80), 1.0, 2.0);
+ Execution earlier = execution(longArn, "z".repeat(80), 1.0, 1.0);
+ executionStore.put(later.getExecutionArn(), later);
+ executionStore.put(earlier.getExecutionArn(), earlier);
+
+ PaginatedResult<StepFunctionsService.ExecutionSnapshot> first = service.listExecutions(
+ longArn, null, 1, null);
+ assertNotNull(first.nextToken());
+ assertTrue(first.nextToken().length() <= 1024,
+ "returned token length was " + first.nextToken().length());
+
+ PaginatedResult<StepFunctionsService.ExecutionSnapshot> second = service.listExecutions(
+ longArn, null, 1, first.nextToken());
+ assertEquals(List.of("z".repeat(80)), second.items().stream()
+ .map(snapshot -> snapshot.execution().getName()).toList());
+ }
+
+ @Test
+ void changingAnExpiredTokensIssueTimeDoesNotExtendItsLifetime() {
+ String token = service.listExecutions(ARN, null, 1, null).nextToken();
+ String payload = Base64Url.decode(token);
+ String scope = "states:executions:" + ACCOUNT + ":" + ARN + ":*";
+ String namespace = "states:executions:" + Base64Url.encode(
+ Digests.sha256(scope.getBytes(StandardCharsets.UTF_8)));
+
+ clock.advance(Duration.ofHours(24).plusMillis(1));
+ int issueTimeEnd = payload.indexOf(':', namespace.length() + 1);
+ String edited = Base64Url.encode(namespace + ":" + clock.millis() + payload.substring(issueTimeEnd));
+
+ AwsException error = assertThrows(AwsException.class,
+ () -> service.listExecutions(ARN, null, 1, edited));
+ assertEquals("InvalidToken", error.getErrorCode());
+ }
+
+ @Test
+ void changingATokensScopeCannotAuthorizeAnotherStateMachine() {
+ String token = service.listExecutions(ARN, null, 1, null).nextToken();
+ String otherArn = ARN + "-other";
+
+ AwsException error = assertThrows(AwsException.class,
+ () -> service.listExecutions(otherArn, null, 1, token));
+ assertEquals("InvalidToken", error.getErrorCode());
+ }
+
+ @Test
+ void continuationTokenIssuedInTheFutureIsRejected() {
+ String token = service.listExecutions(ARN, null, 1, null).nextToken();
+
+ clock.advance(Duration.ofMillis(-1));
+ AwsException error = assertThrows(AwsException.class,
+ () -> service.listExecutions(ARN, null, 1, token));
+ assertEquals("InvalidToken", error.getErrorCode());
+ }
+
+ @Test
+ void malformedContinuationTokenIsRejected() {
+ String scope = "states:executions:" + ACCOUNT + ":" + ARN + ":*:";
+ String malformed = Base64Url.encode(scope + "not-a-time:cursor");
+
+ AwsException error = assertThrows(AwsException.class,
+ () -> service.listExecutions(ARN, null, 1, malformed));
+ assertEquals("InvalidToken", error.getErrorCode());
+ }
+
+ @Test
+ void listExecutionsAcceptsTokensUpToThreeThousandNinetySixCharacters() {
+ for (int length : List.of(1025, 3096)) {
+ AwsException error = assertThrows(AwsException.class,
+ () -> service.listExecutions(ARN, null, 1, "x".repeat(length)));
+ assertEquals("InvalidToken", error.getErrorCode());
+ }
+
+ AwsException tooLong = assertThrows(AwsException.class,
+ () -> service.listExecutions(ARN, null, 1, "x".repeat(3097)));
+ assertEquals("ValidationException", tooLong.getErrorCode());
+ }
+
+ @Test
+ void appliesStatusFilterBeforePaging() {
+ PaginatedResult<StepFunctionsService.ExecutionSnapshot> first = service.listExecutions(
+ ARN, "SUCCEEDED", 1, null);
+ assertEquals(List.of("new"), first.items().stream().map(snapshot -> snapshot.execution().getName())
+ .toList());
+ assertNotNull(first.nextToken());
+
+ PaginatedResult<StepFunctionsService.ExecutionSnapshot> second = service.listExecutions(
+ ARN, "SUCCEEDED", 1, first.nextToken());
+ assertEquals(List.of("old"), second.items().stream().map(snapshot -> snapshot.execution().getName())
+ .toList());
+ }
+
+ @Test
+ void rejectsATokenIssuedForAnotherStateMachineOrFilter() {
+ String token = service.listExecutions(ARN, null, 1, null).nextToken();
+ assertThrows(AwsException.class, () -> service.listExecutions(
+ ARN + "-other", null, 1, token));
+ assertThrows(AwsException.class, () -> service.listExecutions(ARN, "SUCCEEDED", 1, token));
+ }
+
+ @Test
+ void responseStatusIsTheSnapshotUsedByTheFilter() {
+ Execution changing = mock(Execution.class);
+ when(changing.getExecutionArn()).thenReturn(ARN + ":changing");
+ when(changing.getStateMachineArn()).thenReturn(ARN);
+ when(changing.getName()).thenReturn("changing");
+ when(changing.getStatus()).thenReturn("RUNNING", "SUCCEEDED");
+ when(changing.getStartDate()).thenReturn(4.0);
+ executionStore.put(ARN + ":changing", changing);
+
+ StepFunctionsJsonHandler handler = new StepFunctionsJsonHandler(service, new ObjectMapper(), Clock.systemUTC());
+ ObjectNode request = new ObjectMapper().createObjectNode()
+ .put("stateMachineArn", ARN)
+ .put("statusFilter", "RUNNING");
+ JsonNode response = (JsonNode) handler.handle("ListExecutions", request, "us-east-1").getEntity();
+
+ JsonNode changingResponse = response.path("executions").get(0);
+ assertEquals("changing", changingResponse.path("name").asText());
+ assertEquals("RUNNING", changingResponse.path("status").asText());
+ }
+
+ @Test
+ void ordersTerminalExecutionsByStopDateAndResumesStableCursors() {
+ String orderedArn = "arn:aws:states:us-east-1:" + ACCOUNT + ":stateMachine:ordered";
+ Execution terminalA = execution(orderedArn, "terminal-a", 3.0, 5.0);
+ Execution terminalB = execution(orderedArn, "terminal-b", 1.0, 5.0);
+ Execution terminalC = execution(orderedArn, "terminal-c", 9.0, 4.0);
+ executionStore.put(terminalA.getExecutionArn(), terminalA);
+ executionStore.put(terminalB.getExecutionArn(), terminalB);
+ executionStore.put(terminalC.getExecutionArn(), terminalC);
+ doReturn(List.of(terminalB, terminalA, terminalC)).when(executionStore).scan(any());
+
+ PaginatedResult<StepFunctionsService.ExecutionSnapshot> first = service.listExecutions(
+ orderedArn, null, 1, null);
+ assertEquals("terminal-a", first.items().get(0).execution().getName());
+ assertNotNull(first.nextToken());
+
+ PaginatedResult<StepFunctionsService.ExecutionSnapshot> second = service.listExecutions(
+ orderedArn, null, 1, first.nextToken());
+ assertEquals("terminal-b", second.items().get(0).execution().getName());
+ assertNotNull(second.nextToken());
+
+ PaginatedResult<StepFunctionsService.ExecutionSnapshot> third = service.listExecutions(
+ orderedArn, null, 1, second.nextToken());
+ assertEquals("terminal-c", third.items().get(0).execution().getName());
+ assertNull(third.nextToken());
+ }
+
+ private Execution execution(String stateMachineArn, String name, double startDate, double stopDate) {
+ Execution execution = new Execution();
+ execution.setExecutionArn(stateMachineArn + ":execution:" + name);
+ execution.setStateMachineArn(stateMachineArn);
+ execution.setName(name);
+ execution.setStatus("SUCCEEDED");
+ execution.setStartDate(startDate);
+ execution.setStopDate(stopDate);
+ return execution;
+ }
+
+ private void put(String name, double startDate, String status) {
+ Execution execution = new Execution();
+ execution.setExecutionArn(ARN + ":" + name);
+ execution.setStateMachineArn(ARN);
+ execution.setName(name);
+ execution.setStatus(status);
+ execution.setStartDate(startDate);
+ executionStore.put(execution.getExecutionArn(), execution);
+ }
+
+ private static final class MutableClock extends Clock {
+ private Instant current;
+
+ private MutableClock(Instant current) {
+ this.current = current;
+ }
+
+ @Override
+ public ZoneId getZone() {
+ return ZoneOffset.UTC;
+ }
+
+ @Override
+ public Clock withZone(ZoneId zone) {
+ return this;
+ }
+
+ @Override
+ public Instant instant() {
+ return current;
+ }
+
+ private void advance(Duration duration) {
+ current = current.plus(duration);
+ }
+ }
+}