Light, fluffy, and always free - The AWS Local Emulator alternative
add ValidateStateMachineDefinition action (#845)
Marvelous Ikponmwosacf0db6edc955
diff --git a/docs/services/index.md b/docs/services/index.mdindex 3ea1360e8a..6861740508 100644--- a/docs/services/index.md+++ b/docs/services/index.md@@ -25,7 +25,7 @@ Operation counts are exact. For dispatch-table services (Query and JSON 1.1) eac| [KMS](kms.md) | `POST /` + `X-Amz-Target: TrentService.*` | JSON 1.1 | 23 || [Kinesis](kinesis.md) | `POST /` + `X-Amz-Target: Kinesis_20131202.*` | JSON 1.1 | 24 || [Secrets Manager](secrets-manager.md) | `POST /` + `X-Amz-Target: secretsmanager.*` | JSON 1.1 | 16 |-| [Step Functions](step-functions.md) | `POST /` + `X-Amz-Target: AmazonStatesService.*` | JSON 1.1 | 18 |+| [Step Functions](step-functions.md) | `POST /` + `X-Amz-Target: AmazonStatesService.*` | JSON 1.1 | 19 || [CloudFormation](cloudformation.md) | `POST /` with `Action=` param | Query | 19 || [EventBridge](eventbridge.md) | `POST /` + `X-Amz-Target: AmazonEventBridge.*` | JSON 1.1 | 16 || [EventBridge Scheduler](scheduler.md) | `/schedules/*`, `/schedule-groups/*`, `/tags/*` | REST JSON | 12 |diff --git a/docs/services/step-functions.md b/docs/services/step-functions.mdindex 6e8fddf8c7..fdb8ab74f3 100644--- a/docs/services/step-functions.md+++ b/docs/services/step-functions.md@@ -11,6 +11,7 @@| `DescribeStateMachine` | Get state machine definition and metadata || `ListStateMachines` | List all state machines || `DeleteStateMachine` | Delete a state machine |+| `ValidateStateMachineDefinition` | Validate an ASL definition without creating a state machine || `StartExecution` | Start a new execution || `DescribeExecution` | Get execution status and output || `ListExecutions` | List executions for a state machine |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 74b213e74a..db5a51bacd 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@@ -1,6 +1,7 @@package io.github.hectorvent.floci.services.stepfunctions;import io.github.hectorvent.floci.core.common.AwsErrorResponse;+import io.github.hectorvent.floci.core.common.AwsException;import com.fasterxml.jackson.databind.JsonNode;import com.fasterxml.jackson.databind.ObjectMapper;import com.fasterxml.jackson.databind.node.ArrayNode;@@ -36,6 +37,7 @@ public class StepFunctionsJsonHandler {case "DescribeStateMachine" -> handleDescribeStateMachine(request);case "ListStateMachines" -> handleListStateMachines(request, region);case "DeleteStateMachine" -> handleDeleteStateMachine(request);+ case "ValidateStateMachineDefinition" -> handleValidateStateMachineDefinition(request);case "StartExecution" -> handleStartExecution(request, region);case "StartSyncExecution" -> handleStartSyncExecution(request, region);case "DescribeExecution" -> handleDescribeExecution(request);@@ -106,6 +108,32 @@ public class StepFunctionsJsonHandler {return Response.ok(objectMapper.createObjectNode()).build();}+ private Response handleValidateStateMachineDefinition(JsonNode request) {+ String definition = request.path("definition").asText(null);+ String type = request.path("type").asText(null);+ String severity = request.path("severity").asText(null);+ Integer maxResults = parseOptionalInt(request, "maxResults");++ StepFunctionsService.ValidationResult result =+ service.validateStateMachineDefinition(definition, type, severity, maxResults);++ ObjectNode response = objectMapper.createObjectNode();+ response.put("result", result.valid() ? "OK" : "FAIL");+ ArrayNode diags = response.putArray("diagnostics");+ for (StepFunctionsService.Diagnostic d : result.diagnostics()) {+ ObjectNode node = objectMapper.createObjectNode();+ node.put("severity", d.severity());+ node.put("code", d.code());+ node.put("message", d.message());+ if (d.location() != null) {+ node.put("location", d.location());+ }+ diags.add(node);+ }+ response.put("truncated", result.truncated());+ return Response.ok(response).build();+ }+private Response handleStartExecution(JsonNode request, String region) {Execution exec = service.startExecution(request.path("stateMachineArn").asText(),@@ -316,4 +344,24 @@ public class StepFunctionsJsonHandler {return tags;}+ /**+ * Reads an optional integer field from the JSON request, rejecting wrong types+ * with a typed ValidationException. JsonNode.asInt() silently coerces strings,+ * fractional numbers, and explicit nulls to 0, which would let invalid payloads+ * slip through as 0 (and thus be treated as "use default" by the service).+ * Returns null when the field is absent or explicitly null in the JSON.+ */+ private static Integer parseOptionalInt(JsonNode request, String fieldName) {+ JsonNode node = request.get(fieldName);+ if (node == null || node.isNull()) {+ return null;+ }+ if (!node.isIntegralNumber()) {+ throw new AwsException("ValidationException",+ "Value '" + node + "' at '" + fieldName+ + "' failed to satisfy constraint: Member must be an integer.", 400);+ }+ return node.intValue();+ }+}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 73b01a1044..d3034a3008 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@@ -25,6 +25,8 @@ import java.util.concurrent.CompletableFuture;import java.util.concurrent.ConcurrentHashMap;import java.util.concurrent.LinkedBlockingQueue;import java.util.concurrent.TimeUnit;+import java.util.regex.Matcher;+import java.util.regex.Pattern;@ApplicationScopedpublic class StepFunctionsService {@@ -355,13 +357,118 @@ public class StepFunctionsService {// ──────────────────────────── Validation ────────────────────────────+ public record Diagnostic(String severity, String code, String message, String location) {}+ public record ValidationResult(boolean valid, List<Diagnostic> diagnostics, boolean truncated) {}++ private static final int MAX_DEFINITION_LENGTH = 1_048_576;+ private static final String PARSE_ERROR_MARKER = "INVALID_JSON_DESCRIPTION:";++ // Parse the structured location out of the validator's flat error strings,+ // which currently encode it as "...field 'X' is only supported... at /States/Y".+ // AWS's published Diagnostic.location format is "/States/<StateName>/<FieldName>".+ private static final Pattern FIELD_PATTERN = Pattern.compile("field '([^']+)' is only supported");+ private static final Pattern LOCATION_SUFFIX_PATTERN = Pattern.compile(" at (/States/\\S+)$");++ /**+ * Exposes the existing ASL validator as a public, non-throwing API for+ * AWS {@code ValidateStateMachineDefinition}. Errors are returned as+ * diagnostics rather than thrown; no state machine is created. Mirrors+ * the wire shape of the AWS API.+ */+ public ValidationResult validateStateMachineDefinition(String definition, String type,+ String severity, Integer maxResults) {+ if (definition == null || definition.isBlank()) {+ throw new AwsException("ValidationException", "definition is required.", 400);+ }+ if (definition.length() > MAX_DEFINITION_LENGTH) {+ throw new AwsException("ValidationException",+ "definition exceeds maximum length of " + MAX_DEFINITION_LENGTH + " characters.", 400);+ }+ if (maxResults != null && (maxResults < 0 || maxResults > 100)) {+ throw new AwsException("ValidationException",+ "maxResults must be between 0 and 100.", 400);+ }+ if (severity != null && !severity.isBlank()+ && !"ERROR".equals(severity) && !"WARNING".equals(severity)) {+ throw new AwsException("ValidationException",+ "severity must be ERROR or WARNING.", 400);+ }+ if (type != null && !type.isBlank()+ && !"STANDARD".equals(type) && !"EXPRESS".equals(type)) {+ throw new AwsException("ValidationException",+ "type must be STANDARD or EXPRESS.", 400);+ }+ // Per AWS spec: maxResults=0 (or absent/null) → use default of 100.+ // Out-of-range values are rejected above; no clamping needed here.+ int cap = (maxResults == null || maxResults == 0) ? 100 : maxResults;+ List<String> errors = collectValidationErrors(definition);+ List<Diagnostic> all = errors.stream()+ .map(StepFunctionsService::toDiagnostic)+ .toList();++ // Apply the severity filter per spec: ERROR (the default) returns only+ // error diagnostics; WARNING returns both warnings and errors. Floci's+ // validator only emits ERROR today so the filter is currently a no-op,+ // but it's wired now so adding warning-level checks later doesn't break+ // the contract for callers who passed severity=ERROR.+ String effectiveSeverity = severity == null || severity.isBlank() ? "ERROR" : severity;+ List<Diagnostic> filtered = "WARNING".equals(effectiveSeverity)+ ? all+ : all.stream().filter(d -> "ERROR".equals(d.severity())).toList();++ boolean truncated = filtered.size() > cap;+ List<Diagnostic> page = truncated ? filtered.subList(0, cap) : filtered;+ // valid == "no ERROR-level diagnostics". Floci only produces ERRORs today;+ // explicit check future-proofs us when warnings are added.+ boolean valid = page.stream().noneMatch(d -> "ERROR".equals(d.severity()));+ return new ValidationResult(valid, page, truncated);+ }++ private static Diagnostic toDiagnostic(String error) {+ boolean isParseError = error.startsWith(PARSE_ERROR_MARKER);+ String code = isParseError ? "INVALID_JSON_DESCRIPTION" : "SCHEMA_VALIDATION_FAILED";+ String message = isParseError+ ? error.substring(PARSE_ERROR_MARKER.length()).trim() : error;+ // null when there's no specific location to point to — handler omits the+ // field from the response in that case, matching AWS's "optional" semantics.+ String location = null;+ if (!isParseError) {+ Matcher locM = LOCATION_SUFFIX_PATTERN.matcher(message);+ Matcher fieldM = FIELD_PATTERN.matcher(message);+ if (locM.find() && fieldM.find()) {+ // Build the structured location and strip the redundant suffix+ // from the message, matching AWS's wire format.+ location = locM.group(1) + "/" + fieldM.group(1);+ message = message.substring(0, locM.start()).trim();+ }+ }+ return new Diagnostic("ERROR", code, message, location);+ }+private void validateDefinition(String definition) {+ List<String> errors = collectValidationErrors(definition);+ if (errors.isEmpty()) {+ return;+ }+ String first = errors.get(0);+ if (first.startsWith(PARSE_ERROR_MARKER)) {+ // Preserve historical wire shape for parse errors triggered via CreateStateMachine.+ throw new AwsException("InvalidDefinition",+ "Invalid State Machine Definition: '" + first.substring(PARSE_ERROR_MARKER.length()).trim() + "'", 400);+ }+ throw new AwsException("InvalidDefinition",+ "Invalid State Machine Definition: 'SCHEMA_VALIDATION_FAILED: "+ + String.join(", ", errors) + "'", 400);+ }++ private List<String> collectValidationErrors(String definition) {+ List<String> errors = new ArrayList<>();JsonNode def;try {def = objectMapper.readTree(definition);} catch (Exception e) {- throw new AwsException("InvalidDefinition",- "Invalid State Machine Definition: '" + e.getMessage() + "'", 400);+ errors.add(PARSE_ERROR_MARKER + e.getMessage());+ return errors;}String topLevelQL = def.path("QueryLanguage").asText("JSONPath");@@ -370,17 +477,12 @@ public class StepFunctionsService {if (states.isObject()) {var fields = states.fields();- List<String> errors = new ArrayList<>();while (fields.hasNext()) {var entry = fields.next();validateState(entry.getKey(), entry.getValue(), topLevelJsonata, errors);}- if (!errors.isEmpty()) {- throw new AwsException("InvalidDefinition",- "Invalid State Machine Definition: 'SCHEMA_VALIDATION_FAILED: "- + String.join(", ", errors) + "'", 400);- }}+ return errors;}private void validateState(String stateName, JsonNode stateDef, boolean topLevelJsonata, List<String> errors) {diff --git a/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsValidateStateMachineDefinitionIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsValidateStateMachineDefinitionIntegrationTest.javanew file mode 100644index 0000000000..33f1c1ba3d--- /dev/null+++ b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsValidateStateMachineDefinitionIntegrationTest.java@@ -0,0 +1,223 @@+package io.github.hectorvent.floci.services.stepfunctions;++import io.github.hectorvent.floci.testing.RestAssuredJsonUtils;+import io.quarkus.test.junit.QuarkusTest;+import io.restassured.response.Response;+import org.junit.jupiter.api.Assertions;+import org.junit.jupiter.api.BeforeAll;+import org.junit.jupiter.api.Test;++import static io.restassured.RestAssured.given;+import static org.hamcrest.Matchers.containsString;+import static org.hamcrest.Matchers.equalTo;+import static org.hamcrest.Matchers.greaterThanOrEqualTo;+import static org.hamcrest.Matchers.hasSize;+import static org.hamcrest.Matchers.is;+import static org.hamcrest.Matchers.not;+import static org.hamcrest.Matchers.nullValue;+import static org.hamcrest.Matchers.startsWith;++/**+ * Integration tests for SFN ValidateStateMachineDefinition via the JSON 1.0 wire path.+ * All wire fields are lowercase per the official AWS spec.+ */+@QuarkusTest+class StepFunctionsValidateStateMachineDefinitionIntegrationTest {++ private static final String CT = "application/x-amz-json-1.0";+ private static final String TARGET = "AWSStepFunctions.ValidateStateMachineDefinition";+ private static final String LIST_TARGET = "AWSStepFunctions.ListStateMachines";++ // ASL with the inner double-quotes already JSON-escaped, so it embeds cleanly+ // inside the outer JSON request body as the value of "definition".+ private static final String VALID_ASL =+ "{\\\"StartAt\\\":\\\"Done\\\",\\\"States\\\":{\\\"Done\\\":{\\\"Type\\\":\\\"Pass\\\",\\\"End\\\":true}}}";++ // JSONata state declaring three JSONPath-only fields → 3 distinct errors.+ private static final String JSONATA_WITH_3_JSONPATH_FIELDS =+ "{\\\"QueryLanguage\\\":\\\"JSONata\\\",\\\"StartAt\\\":\\\"X\\\","+ + "\\\"States\\\":{\\\"X\\\":{\\\"Type\\\":\\\"Pass\\\",\\\"End\\\":true,"+ + "\\\"InputPath\\\":\\\"$.a\\\","+ + "\\\"OutputPath\\\":\\\"$.b\\\","+ + "\\\"ResultPath\\\":\\\"$.c\\\"}}}";++ @BeforeAll+ static void configure() {+ RestAssuredJsonUtils.configureAwsContentTypes();+ }++ @Test+ void validDefinition_returnsOK() {+ given().contentType(CT).header("X-Amz-Target", TARGET)+ .body("{\"definition\":\"" + VALID_ASL + "\"}")+ .when().post("/")+ .then().statusCode(200)+ .body("result", equalTo("OK"))+ .body("diagnostics", hasSize(0))+ .body("truncated", is(false));+ }++ @Test+ void malformedJson_returnsFailWithInvalidJson() {+ given().contentType(CT).header("X-Amz-Target", TARGET)+ .body("{\"definition\":\"{not json\"}")+ .when().post("/")+ .then().statusCode(200)+ .body("result", equalTo("FAIL"))+ .body("diagnostics", hasSize(1))+ .body("diagnostics[0].severity", equalTo("ERROR"))+ .body("diagnostics[0].code", equalTo("INVALID_JSON_DESCRIPTION"))+ // No location for JSON parse errors — there's no state path to point to yet.+ .body("diagnostics[0].location", nullValue());+ }++ @Test+ void jsonataStateWithJsonpathField_returnsFailWithSchemaError() {+ // A single JSONata state declaring InputPath → exactly 1 error.+ String def = "{\\\"QueryLanguage\\\":\\\"JSONata\\\",\\\"StartAt\\\":\\\"X\\\","+ + "\\\"States\\\":{\\\"X\\\":{\\\"Type\\\":\\\"Pass\\\",\\\"End\\\":true,"+ + "\\\"InputPath\\\":\\\"$.a\\\"}}}";+ given().contentType(CT).header("X-Amz-Target", TARGET)+ .body("{\"definition\":\"" + def + "\"}")+ .when().post("/")+ .then().statusCode(200)+ .body("result", equalTo("FAIL"))+ .body("diagnostics", hasSize(1))+ .body("diagnostics[0].severity", equalTo("ERROR"))+ .body("diagnostics[0].code", equalTo("SCHEMA_VALIDATION_FAILED"))+ .body("diagnostics[0].location", equalTo("/States/X/InputPath"));+ }++ @Test+ void emptyDefinition_returns400() {+ given().contentType(CT).header("X-Amz-Target", TARGET)+ .body("{\"definition\":\"\"}")+ .when().post("/")+ .then().statusCode(400)+ .body("__type", containsString("ValidationException"));+ }++ @Test+ void missingDefinition_returns400() {+ given().contentType(CT).header("X-Amz-Target", TARGET)+ .body("{}")+ .when().post("/")+ .then().statusCode(400)+ .body("__type", containsString("ValidationException"));+ }++ @Test+ void maxResultsTruncates() {+ given().contentType(CT).header("X-Amz-Target", TARGET)+ .body("{\"definition\":\"" + JSONATA_WITH_3_JSONPATH_FIELDS + "\",\"maxResults\":1}")+ .when().post("/")+ .then().statusCode(200)+ .body("result", equalTo("FAIL"))+ .body("diagnostics", hasSize(1))+ .body("truncated", is(true));+ }++ @Test+ void maxResultsZeroUsesDefault() {+ // Per AWS spec: maxResults=0 means "use default of 100", not "return zero".+ // The 3 errors from JSONATA_WITH_3_JSONPATH_FIELDS all fit under 100 → no truncation.+ given().contentType(CT).header("X-Amz-Target", TARGET)+ .body("{\"definition\":\"" + JSONATA_WITH_3_JSONPATH_FIELDS + "\",\"maxResults\":0}")+ .when().post("/")+ .then().statusCode(200)+ .body("result", equalTo("FAIL"))+ .body("diagnostics", hasSize(3))+ .body("truncated", is(false));+ }++ @Test+ void validDefinition_doesNotTouchStorage() {+ // Snapshot the state-machine list, validate a definition, snapshot again — must match.+ int before = given().contentType(CT).header("X-Amz-Target", LIST_TARGET)+ .body("{}")+ .when().post("/")+ .then().statusCode(200)+ .extract().jsonPath().getList("stateMachines").size();++ given().contentType(CT).header("X-Amz-Target", TARGET)+ .body("{\"definition\":\"" + VALID_ASL + "\"}")+ .when().post("/")+ .then().statusCode(200);++ int after = given().contentType(CT).header("X-Amz-Target", LIST_TARGET)+ .body("{}")+ .when().post("/")+ .then().statusCode(200)+ .extract().jsonPath().getList("stateMachines").size();++ // Same count proves validate didn't create a state machine.+ Assertions.assertEquals(before, after,+ "validate must not touch storage (before=" + before + " after=" + after + ")");+ }++ @Test+ void typeParameterAccepted() {+ // Floci's validator is type-agnostic; the param round-trips without changing behavior.+ given().contentType(CT).header("X-Amz-Target", TARGET)+ .body("{\"definition\":\"" + VALID_ASL + "\",\"type\":\"EXPRESS\"}")+ .when().post("/")+ .then().statusCode(200)+ .body("result", equalTo("OK"));+ }++ @Test+ void maxResultsAbove100Rejected() {+ given().contentType(CT).header("X-Amz-Target", TARGET)+ .body("{\"definition\":\"" + VALID_ASL + "\",\"maxResults\":101}")+ .when().post("/")+ .then().statusCode(400)+ .body("__type", containsString("ValidationException"));+ }++ @Test+ void maxResultsBelowZeroRejected() {+ given().contentType(CT).header("X-Amz-Target", TARGET)+ .body("{\"definition\":\"" + VALID_ASL + "\",\"maxResults\":-1}")+ .when().post("/")+ .then().statusCode(400)+ .body("__type", containsString("ValidationException"));+ }++ @Test+ void severityInvalidEnumRejected() {+ given().contentType(CT).header("X-Amz-Target", TARGET)+ .body("{\"definition\":\"" + VALID_ASL + "\",\"severity\":\"GARBAGE\"}")+ .when().post("/")+ .then().statusCode(400)+ .body("__type", containsString("ValidationException"));+ }++ @Test+ void typeInvalidEnumRejected() {+ given().contentType(CT).header("X-Amz-Target", TARGET)+ .body("{\"definition\":\"" + VALID_ASL + "\",\"type\":\"BOGUS\"}")+ .when().post("/")+ .then().statusCode(400)+ .body("__type", containsString("ValidationException"));+ }++ @Test+ void maxResultsNonIntegerRejected() {+ // JsonNode.asInt() would silently coerce "abc" to 0, which the service then+ // treats as "use default". Reject at the handler boundary instead.+ given().contentType(CT).header("X-Amz-Target", TARGET)+ .body("{\"definition\":\"" + VALID_ASL + "\",\"maxResults\":\"abc\"}")+ .when().post("/")+ .then().statusCode(400)+ .body("__type", containsString("ValidationException"));+ }++ @Test+ void maxResultsFractionalRejected() {+ given().contentType(CT).header("X-Amz-Target", TARGET)+ .body("{\"definition\":\"" + VALID_ASL + "\",\"maxResults\":1.7}")+ .when().post("/")+ .then().statusCode(400)+ .body("__type", containsString("ValidationException"));+ }+}