Light, fluffy, and always free - The AWS Local Emulator alternative
feat(stepfunctions): add the JSONata functions of the Step Functions dialect (#2676)
Facundo Paredeseb5134da2d76
diff --git a/docs/services/step-functions.md b/docs/services/step-functions.mdindex 0e8f39f3bf..bb096666df 100644--- a/docs/services/step-functions.md+++ b/docs/services/step-functions.md@@ -66,6 +66,34 @@ uniformly between zero and the computed delay, as on AWS. One deviation. The delbetween attempts is capped at 30 seconds, the same cap Floci applies to `Wait` states,so emulated runs stay fast.+## JSONata functions++State machines with `"QueryLanguage": "JSONata"` reach the six functions Step Functions adds on+top of the JSONata language, alongside every function JSONata itself provides.++| Function | Returns |+| --- | --- |+| `$parse(jsonString)` | the deserialized value; the replacement for `$eval`, which AWS disables |+| `$partition(array, chunkSize)` | `array` split into chunks of `chunkSize`, the last one holding the remainder |+| `$range(start, end, step)` | the values from `start` to `end`, inclusive when `step` lands on `end` |+| `$hash(str, algorithm)` | the hex digest of `str`; `algorithm` is `MD5`, `SHA-1`, `SHA-256`, `SHA-384` or `SHA-512`, case-sensitive |+| `$random(seed)` | a number in `[0, 1)`, reproducible under the optional integer `seed` |+| `$uuid()` | a v4 UUID |++Three behaviours are worth knowing before reading an unexpected result, and all three are AWS's:++- A non-integer argument is rounded **towards zero**, so `$range(-1.7, 2, 1)` starts at `-1` and+ `$partition(items, 2.9)` chunks by 2.+- Several arguments evaluate to undefined rather than failing: a chunk size of zero, an empty+ array, a `$range` with no `step` or with a step whose sign disagrees with the direction, and a+ `$hash` with no algorithm. An undefined value is then dropped from the surrounding `Output`+ object, so the field goes missing instead of the state failing.+- `$range` collapses a single-element range to the bare number, not a one-element array.++One deviation. AWS bounds the memory an expression may use and fails a `$range` of roughly half a+million elements with `Expression evaluation memory limit exceeded`; Floci has no such bound and+builds the array.+## Mocked service integrationsFloci supports the Step Functions Local mock configuration formatdiff --git a/src/main/java/io/github/hectorvent/floci/services/stepfunctions/JsonataEvaluator.java b/src/main/java/io/github/hectorvent/floci/services/stepfunctions/JsonataEvaluator.javaindex c9fb13d78e..5ead99c0b9 100644--- a/src/main/java/io/github/hectorvent/floci/services/stepfunctions/JsonataEvaluator.java+++ b/src/main/java/io/github/hectorvent/floci/services/stepfunctions/JsonataEvaluator.java@@ -1,16 +1,33 @@package io.github.hectorvent.floci.services.stepfunctions;+import com.dashjoin.jsonata.JException;import com.dashjoin.jsonata.Jsonata;+import com.fasterxml.jackson.core.JsonParser;+import com.fasterxml.jackson.core.JsonProcessingException;+import com.fasterxml.jackson.databind.DeserializationFeature;import com.fasterxml.jackson.databind.JsonNode;import com.fasterxml.jackson.databind.ObjectMapper;+import com.fasterxml.jackson.databind.ObjectReader;import com.fasterxml.jackson.databind.node.ArrayNode;import com.fasterxml.jackson.databind.node.NullNode;import com.fasterxml.jackson.databind.node.ObjectNode;import jakarta.enterprise.context.ApplicationScoped;import jakarta.inject.Inject;+import java.math.BigInteger;+import java.nio.charset.StandardCharsets;+import java.security.MessageDigest;+import java.security.NoSuchAlgorithmException;+import java.util.ArrayList;+import java.util.HexFormat;import java.util.Iterator;+import java.util.LinkedHashMap;+import java.util.List;import java.util.Map;+import java.util.Random;+import java.util.Set;+import java.util.UUID;+import java.util.concurrent.ThreadLocalRandom;import static io.github.hectorvent.floci.services.stepfunctions.AslExecutor.FailStateException;@@ -28,11 +45,28 @@ import static com.dashjoin.jsonata.Jsonata.jsonata;@ApplicationScopedpublic class JsonataEvaluator {+ private static final Set<String> HASH_ALGORITHMS = Set.of("MD5", "SHA-1", "SHA-256", "SHA-384", "SHA-512");++ /**+ * The largest magnitude a {@code double} can still hold as an exact integer count of longs.+ * Past it AWS switches from an integer to exponent notation, and so does {@link #toJsonataValue}.+ */+ private static final double LARGEST_EXACT_LONG_AS_DOUBLE = 9.223372036854776E18;+private final ObjectMapper objectMapper;+ private final ObjectReader strictJsonReader;+ private final Map<String, Jsonata.JFunction> stepFunctionsExtensions;@Injectpublic JsonataEvaluator(ObjectMapper objectMapper) {this.objectMapper = objectMapper;+ // AWS rejects what a lenient parser accepts: a second document after the first, a repeated+ // key, an empty string. All three come back as D3137 there, so $parse reads through this+ // reader rather than the shared mapper, whose settings belong to the wire protocol.+ this.strictJsonReader = objectMapper.reader()+ .with(DeserializationFeature.FAIL_ON_TRAILING_TOKENS)+ .with(JsonParser.Feature.STRICT_DUPLICATE_DETECTION);+ this.stepFunctionsExtensions = buildStepFunctionsExtensions();}/**@@ -71,6 +105,7 @@ public class JsonataEvaluator {try {Jsonata jsonataExpr = jsonata(expr);Jsonata.Frame frame = jsonataExpr.createFrame();+ stepFunctionsExtensions.forEach(frame::bind);// Workflow variables (the Assign field) are referenced as top-level $name in AWS's// JSONata dialect, e.g. $CheckpointCount. They are bound alongside $states, never// inside it: AWS reserves $states for input/result/errorOutput/context only. $states is@@ -160,4 +195,272 @@ public class JsonataEvaluator {}return objectMapper.valueToTree(value);}++ /**+ * The six JSONata functions the Step Functions dialect adds on top of the JSONata language,+ * per https://docs.aws.amazon.com/step-functions/latest/dg/transforming-data.html. Five of+ * them the dashjoin library does not have at all; $random it has with the wrong arity, so the+ * binding shadows it to accept AWS's optional seed.+ *+ * <p>Each signature declares one optional slot more than the arity AWS documents. The library+ * pads a short call with Java nulls up to the declared arity and refuses a call longer than+ * it, so the extra slot is what lets an over-long call reach this code and fail with AWS's own+ * message instead of the library's. A signature is also what makes the function usable as a+ * value: dashjoin dereferences it unconditionally in $map, $filter, $sift, $each, $single and+ * $reduce, and a null one throws a raw NullPointerException there.+ */+ private Map<String, Jsonata.JFunction> buildStepFunctionsExtensions() {+ return Map.of(+ "parse", new Jsonata.JFunction((input, arguments) -> parse(arguments), "<x?x?:x>"),+ "partition", new Jsonata.JFunction((input, arguments) -> partition(arguments), "<x?x?x?:x>"),+ "range", new Jsonata.JFunction((input, arguments) -> range(arguments), "<x?x?x?x?:x>"),+ "hash", new Jsonata.JFunction((input, arguments) -> hash(arguments), "<x?x?x?:x>"),+ "random", new Jsonata.JFunction((input, arguments) -> random(arguments), "<x?x?:x>"),+ "uuid", new Jsonata.JFunction((input, arguments) -> uuid(arguments), "<x?:x>"));+ }++ /**+ * The argument in a slot, or null when the caller left it out. A higher-order call such as+ * {@code $map(items, $parse)} passes only the arguments it has, so the list can be shorter+ * than the declared arity.+ */+ private static Object argument(List<Object> arguments, int index) {+ return index < arguments.size() ? arguments.get(index) : null;+ }++ /**+ * AWS refuses a call with more arguments than the function takes, naming the first surplus+ * one. The signatures declare that slot so the surplus argument arrives here to be named.+ */+ private static void rejectSurplusArgument(List<Object> arguments, String functionName, int firstSurplusIndex) {+ if (argument(arguments, firstSurplusIndex) != null) {+ throw signatureError(functionName, firstSurplusIndex + 1);+ }+ }++ private static JException signatureError(String functionName, int argumentNumber) {+ return new JException("T0410: Argument " + argumentNumber + " of function \"" + functionName+ + "\" does not match function signature", -1);+ }++ /**+ * AWS rounds a non-integer argument towards zero, so -1.7 becomes -1 and 2.9 becomes 2, which+ * is what a Java cast already does. Flooring instead shifts every negative argument by one.+ */+ private static long towardsZero(Object argument, String functionName, int argumentNumber) {+ if (!(argument instanceof Number number)) {+ throw signatureError(functionName, argumentNumber);+ }+ return (long) number.doubleValue();+ }++ /**+ * $parse(jsonString): deserializes a JSON string, replacing AWS's disabled $eval. A missing+ * argument evaluates to undefined (Java null); a non-string argument or JSON that AWS's+ * parser refuses raises a JSONata error.+ */+ private Object parse(List<Object> arguments) {+ rejectSurplusArgument(arguments, "parse", 1);+ Object jsonArgument = argument(arguments, 0);+ if (jsonArgument == null) {+ return null;+ }+ if (!(jsonArgument instanceof String jsonString)) {+ throw signatureError("parse", 1);+ }+ JsonNode parsed;+ try {+ parsed = strictJsonReader.readTree(jsonString);+ } catch (JsonProcessingException e) {+ throw new JException("D3137: Invalid JSON", -1);+ }+ // An empty or blank string parses to a missing node rather than raising. AWS calls it+ // invalid JSON, and letting it through would turn an empty upstream body into "".+ if (parsed == null || parsed.isMissingNode()) {+ throw new JException("D3137: Invalid JSON", -1);+ }+ return toJsonataValue(parsed);+ }++ /**+ * Converts a parsed JSON tree into plain Java values that JSONata can navigate as a path,+ * using the JSONata null marker (not Java null, which JSONata reads as undefined) for JSON+ * null so $exists() on a parsed null stays true, as it does on AWS.+ */+ private static Object toJsonataValue(JsonNode node) {+ if (node.isNull()) {+ return Jsonata.NULL_VALUE;+ }+ if (node.isObject()) {+ Map<String, Object> map = new LinkedHashMap<>();+ node.fields().forEachRemaining(entry -> map.put(entry.getKey(), toJsonataValue(entry.getValue())));+ return map;+ }+ if (node.isArray()) {+ List<Object> list = new ArrayList<>();+ node.forEach(element -> list.add(toJsonataValue(element)));+ return list;+ }+ if (node.isBoolean()) {+ return node.booleanValue();+ }+ if (node.isNumber()) {+ return toJsonataNumber(node);+ }+ return node.asText();+ }++ /**+ * AWS keeps a JSON integer exact while it fits in a long and switches to a double past that,+ * so 9223372036854775807 stays itself and 9223372036854775808 comes back as+ * 9.223372036854776E18. It also drops a trailing zero, writing 1.0 as 1 and 1e2 as 100.+ *+ * <p>Reading every integer as a long regardless of width is what makes a number larger than a+ * long come back negative.+ */+ private static Object toJsonataNumber(JsonNode node) {+ if (node.isIntegralNumber() && node.canConvertToLong()) {+ return node.longValue();+ }+ double value = node.doubleValue();+ if (!Double.isFinite(value)) {+ throw new JException("D3137: Invalid JSON", -1);+ }+ if (value == Math.rint(value) && Math.abs(value) < LARGEST_EXACT_LONG_AS_DOUBLE) {+ return (long) value;+ }+ return value;+ }++ /**+ * $partition(array, chunkSize): splits array into chunks of chunkSize elements, the last chunk+ * holding the remainder. A missing chunk size returns the whole array as one chunk; a missing+ * array, an empty array and a chunk size that rounds to zero evaluate to undefined (Java+ * null); a chunk size that rounds below zero raises D3137, and a non-array first argument or a+ * non-numeric chunk size raises a JSONata signature error. Rounding towards zero is what makes+ * -0.5 undefined and -2 an error.+ */+ private static Object partition(List<Object> arguments) {+ rejectSurplusArgument(arguments, "partition", 2);+ Object arrayArgument = argument(arguments, 0);+ if (arrayArgument == null) {+ return null;+ }+ if (!(arrayArgument instanceof List<?> array)) {+ throw new JException("T0412: Argument 1 of function \"partition\" must be an array of undefined", -1);+ }+ if (array.isEmpty()) {+ return null;+ }+ Object chunkSizeArgument = argument(arguments, 1);+ if (chunkSizeArgument == null) {+ return List.of(array);+ }+ long chunkSize = towardsZero(chunkSizeArgument, "partition", 2);+ if (chunkSize < 0) {+ throw new JException("D3137: Second argument must be zero or greater", -1);+ }+ if (chunkSize == 0) {+ return null;+ }+ List<Object> chunks = new ArrayList<>();+ int size = (int) Math.min(chunkSize, array.size());+ for (int i = 0; i < array.size(); i += size) {+ chunks.add(new ArrayList<>(array.subList(i, Math.min(i + size, array.size()))));+ }+ return chunks;+ }++ /**+ * $range(start, end, step): generates an array from start to end (inclusive, when the step+ * lands on it). A single-element range collapses to the bare scalar, not a one-element array;+ * a missing or zero step, or a step whose sign disagrees with the start/end direction,+ * evaluates to undefined (Java null); a missing start or end raises a JSONata error.+ */+ private static Object range(List<Object> arguments) {+ rejectSurplusArgument(arguments, "range", 3);+ long start = towardsZero(argument(arguments, 0), "range", 1);+ long end = towardsZero(argument(arguments, 1), "range", 2);+ Object stepArgument = argument(arguments, 2);+ if (stepArgument == null) {+ return null;+ }+ long step = towardsZero(stepArgument, "range", 3);+ if (step == 0 || (step > 0 && start > end) || (step < 0 && start < end)) {+ return null;+ }+ if (start == end) {+ return start;+ }+ // Counted in BigInteger, then iterated a fixed number of times. Walking the range with+ // `v += step` and testing `v <= end` never terminates once the addition wraps: with a step+ // near Long.MAX_VALUE the sum flips sign and lands back below the end on every pass.+ BigInteger elements = BigInteger.valueOf(end)+ .subtract(BigInteger.valueOf(start))+ .divide(BigInteger.valueOf(step))+ .add(BigInteger.ONE);+ List<Object> values = new ArrayList<>();+ long value = start;+ for (BigInteger emitted = BigInteger.ZERO;+ emitted.compareTo(elements) < 0;+ emitted = emitted.add(BigInteger.ONE)) {+ values.add(value);+ value += step;+ }+ return values;+ }++ /**+ * $hash(str, algorithm): hex-encoded digest of str using algorithm, one of MD5, SHA-1,+ * SHA-256, SHA-384 or SHA-512 (case-sensitive). A missing or non-string str raises a JSONata+ * signature error, a missing algorithm evaluates to undefined (Java null), and an algorithm+ * name that is a string but not one of the five raises D3137: that is the split AWS makes+ * between a wrong type and a wrong value.+ */+ private static Object hash(List<Object> arguments) {+ rejectSurplusArgument(arguments, "hash", 2);+ if (!(argument(arguments, 0) instanceof String value)) {+ throw signatureError("hash", 1);+ }+ Object algorithmArgument = argument(arguments, 1);+ if (algorithmArgument == null) {+ return null;+ }+ if (!(algorithmArgument instanceof String algorithm)) {+ throw signatureError("hash", 2);+ }+ if (!HASH_ALGORITHMS.contains(algorithm)) {+ throw new JException("D3137: Hash algorithm '" + algorithm+ + "' must be one of SHA-1, SHA-384, SHA-256, SHA-512, MD5", -1);+ }+ try {+ MessageDigest digest = MessageDigest.getInstance(algorithm);+ return HexFormat.of().formatHex(digest.digest(value.getBytes(StandardCharsets.UTF_8)));+ } catch (NoSuchAlgorithmException e) {+ throw new JException("Hash algorithm '" + algorithm + "' is not available", -1);+ }+ }++ /**+ * $random(seed): a number in [0, 1). JSONata's own $random takes no arguments; the Step+ * Functions one takes an optional integer seed and is reproducible under it. AWS draws from+ * java.util.Random, so seeding one with the same value returns the same sequence: $random(42)+ * is 0.7275636800328681 on both sides.+ */+ private static Object random(List<Object> arguments) {+ rejectSurplusArgument(arguments, "random", 1);+ Object seedArgument = argument(arguments, 0);+ if (seedArgument == null) {+ return ThreadLocalRandom.current().nextDouble();+ }+ return new Random(towardsZero(seedArgument, "random", 1)).nextDouble();+ }++ /**+ * $uuid(): a random v4 UUID. Strictly zero-arity; any argument raises a JSONata error.+ */+ private static Object uuid(List<Object> arguments) {+ rejectSurplusArgument(arguments, "uuid", 0);+ return UUID.randomUUID().toString();+ }}diff --git a/src/test/java/io/github/hectorvent/floci/services/stepfunctions/JsonataEvaluatorTest.java b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/JsonataEvaluatorTest.javaindex 2305c8ee47..5ec2a39fbd 100644--- a/src/test/java/io/github/hectorvent/floci/services/stepfunctions/JsonataEvaluatorTest.java+++ b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/JsonataEvaluatorTest.java@@ -173,4 +173,380 @@ class JsonataEvaluatorTest {assertTrue(evaluator.resolveTemplate(objectMapper.readTree("true"), statesVar).asBoolean());assertTrue(evaluator.resolveTemplate(NullNode.getInstance(), statesVar).isNull());}++ @Test+ void parse_deserializesJsonObject() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $parse('{\"a\":1,\"b\":[1,2,3]}') %}", statesVar);+ assertTrue(result.isObject());+ assertEquals(1, result.get("a").asInt());+ assertEquals(3, result.get("b").size());+ }++ @Test+ void parse_navigatesFieldOffResult() throws Exception {+ // The dominant real-world shape: $parse(x.Output).someField.+ JsonNode statesVar = objectMapper.readTree("""+ {"eligibilityRaw": {"Output": "{\\"joinable\\": true}"}}+ """);+ JsonNode result = evaluator.evaluate("{% $parse($states.eligibilityRaw.Output).joinable %}", statesVar);+ assertTrue(result.asBoolean());+ }++ @Test+ void parse_chainedWithArithmeticOnNestedField() throws Exception {+ // Real acceptance shape: $round($parse($states.input[0].body).detail.amount.value * 100)+ JsonNode statesVar = objectMapper.readTree("""+ {"input": [{"body": "{\\"detail\\": {\\"amount\\": {\\"value\\": 12.345}}}"}]}+ """);+ JsonNode result = evaluator.evaluate(+ "{% $round($parse($states.input[0].body).detail.amount.value * 100) %}", statesVar);+ assertEquals(1234, result.asInt());+ }++ @Test+ void parse_nullLiteralIsRealNullNotUndefined() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $exists($parse('null')) %}", statesVar);+ assertTrue(result.asBoolean());+ }++ @Test+ void parse_noArgumentReturnsUndefined() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $parse() %}", statesVar);+ assertTrue(result.isNull());+ }++ @Test+ void parse_nullArgumentRaisesSignatureError() {+ JsonNode statesVar = objectMapper.createObjectNode();+ AslExecutor.FailStateException ex = assertThrows(AslExecutor.FailStateException.class,+ () -> evaluator.evaluate("{% $parse(null) %}", statesVar));+ assertTrue(ex.cause.contains("T0410"));+ }++ @Test+ void parse_invalidJsonRaisesError() {+ JsonNode statesVar = objectMapper.createObjectNode();+ AslExecutor.FailStateException ex = assertThrows(AslExecutor.FailStateException.class,+ () -> evaluator.evaluate("{% $parse('not valid json') %}", statesVar));+ assertTrue(ex.cause.contains("D3137"));+ }++ @Test+ void partition_splitsIntoChunksWithShorterLastChunk() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $partition([1,2,3,4,5], 2) %}", statesVar);+ assertEquals("[[1,2],[3,4],[5]]", result.toString());+ }++ @Test+ void partition_missingChunkSizeReturnsWholeArrayAsOneChunk() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $partition([1,2,3]) %}", statesVar);+ assertEquals("[[1,2,3]]", result.toString());+ }++ @Test+ void partition_nonIntegerChunkSizeIsRoundedTowardsZero() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $partition([1,2,3,4,5], 2.9) %}", statesVar);+ assertEquals("[[1,2],[3,4],[5]]", result.toString());+ }++ @Test+ void partition_emptyArrayReturnsUndefined() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $partition([], 2) %}", statesVar);+ assertTrue(result.isNull());+ }++ @Test+ void partition_chunkSizeZeroReturnsUndefined() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $partition([1,2,3], 0) %}", statesVar);+ assertTrue(result.isNull());+ }++ @Test+ void partition_negativeChunkSizeRaisesError() {+ JsonNode statesVar = objectMapper.createObjectNode();+ AslExecutor.FailStateException ex = assertThrows(AslExecutor.FailStateException.class,+ () -> evaluator.evaluate("{% $partition([1,2,3], -1) %}", statesVar));+ assertTrue(ex.cause.contains("D3137: Second argument must be zero or greater"), ex.cause);+ }++ @Test+ void partition_nullArrayRaisesError() {+ JsonNode statesVar = objectMapper.createObjectNode();+ AslExecutor.FailStateException ex = assertThrows(AslExecutor.FailStateException.class,+ () -> evaluator.evaluate("{% $partition(null, 2) %}", statesVar));+ assertTrue(ex.cause.contains("T0412"));+ }++ @Test+ void range_generatesInclusiveAscendingArray() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $range(0, 10, 2) %}", statesVar);+ assertEquals("[0,2,4,6,8,10]", result.toString());+ }++ @Test+ void range_negativeStepGeneratesDescendingArray() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $range(10, 0, -2) %}", statesVar);+ assertEquals("[10,8,6,4,2,0]", result.toString());+ }++ @Test+ void range_nonIntegerStartIsRoundedTowardsZero() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $range(1.7, 5, 1) %}", statesVar);+ assertEquals("[1,2,3,4,5]", result.toString());+ }++ @Test+ void range_singleElementRangeCollapsesToScalar() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $range(3, 3, 1) %}", statesVar);+ assertTrue(result.isNumber());+ assertEquals(3, result.asInt());+ }++ @Test+ void range_wrongSignStepReturnsUndefined() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $range(5, 1, 1) %}", statesVar);+ assertTrue(result.isNull());+ }++ @Test+ void range_stepZeroReturnsUndefined() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $range(1, 5, 0) %}", statesVar);+ assertTrue(result.isNull());+ }++ @Test+ void range_missingStepReturnsUndefined() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $range(1, 5) %}", statesVar);+ assertTrue(result.isNull());+ }++ @Test+ void range_missingEndRaisesSignatureError() {+ JsonNode statesVar = objectMapper.createObjectNode();+ AslExecutor.FailStateException ex = assertThrows(AslExecutor.FailStateException.class,+ () -> evaluator.evaluate("{% $range(1) %}", statesVar));+ assertTrue(ex.cause.contains("T0410"));+ }++ @Test+ void hash_computesKnownDigestsForEachAlgorithm() {+ JsonNode statesVar = objectMapper.createObjectNode();+ assertEquals("8b1a9953c4611296a827abf8c47804d7",+ evaluator.evaluate("{% $hash('Hello', 'MD5') %}", statesVar).asText());+ assertEquals("f7ff9e8b7bb2e09b70935a5d785e0cc5d9d0abf0",+ evaluator.evaluate("{% $hash('Hello', 'SHA-1') %}", statesVar).asText());+ assertEquals("185f8db32271fe25f561a6fc938b2e264306ec304eda518007d1764826381969",+ evaluator.evaluate("{% $hash('Hello', 'SHA-256') %}", statesVar).asText());+ }++ @Test+ void hash_algorithmNameIsCaseSensitive() {+ JsonNode statesVar = objectMapper.createObjectNode();+ AslExecutor.FailStateException ex = assertThrows(AslExecutor.FailStateException.class,+ () -> evaluator.evaluate("{% $hash('Hello', 'md5') %}", statesVar));+ assertTrue(ex.cause.contains("D3137"));+ }++ @Test+ void hash_unsupportedAlgorithmRaisesError() {+ JsonNode statesVar = objectMapper.createObjectNode();+ AslExecutor.FailStateException ex = assertThrows(AslExecutor.FailStateException.class,+ () -> evaluator.evaluate("{% $hash('Hello', 'SHA3-256') %}", statesVar));+ assertTrue(ex.cause.contains("D3137"));+ }++ @Test+ void hash_missingAlgorithmReturnsUndefined() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $hash('Hello') %}", statesVar);+ assertTrue(result.isNull());+ }++ @Test+ void hash_nonStringValueRaisesSignatureError() {+ JsonNode statesVar = objectMapper.createObjectNode();+ AslExecutor.FailStateException ex = assertThrows(AslExecutor.FailStateException.class,+ () -> evaluator.evaluate("{% $hash(42, 'MD5') %}", statesVar));+ assertTrue(ex.cause.contains("T0410"));+ }++ @Test+ void uuid_generatesCanonicalV4Uuid() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $uuid() %}", statesVar);+ assertTrue(result.asText()+ .matches("^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"));+ }++ @Test+ void uuid_successiveCallsAreDistinct() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $uuid() = $uuid() %}", statesVar);+ assertFalse(result.asBoolean());+ }++ @Test+ void uuid_anyArgumentRaisesSignatureError() {+ JsonNode statesVar = objectMapper.createObjectNode();+ AslExecutor.FailStateException ex = assertThrows(AslExecutor.FailStateException.class,+ () -> evaluator.evaluate("{% $uuid('seed') %}", statesVar));+ assertTrue(ex.cause.contains("T0410"));+ }++ @Test+ void random_unseededCallsDiffer() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $random() = $random() %}", statesVar);+ assertFalse(result.asBoolean());+ }++ @Test+ void random_seedMakesTheDrawReproducible() {+ // JSONata's own $random takes no arguments; the Step Functions one takes a seed and draws+ // from java.util.Random, so these are the values AWS returns for the same seeds.+ JsonNode statesVar = objectMapper.createObjectNode();+ assertEquals(0.7275636800328681, evaluator.evaluate("{% $random(42) %}", statesVar).asDouble());+ assertEquals(0.730967787376657, evaluator.evaluate("{% $random(0) %}", statesVar).asDouble());+ assertEquals(0.7306990420600421, evaluator.evaluate("{% $random(7) %}", statesVar).asDouble());+ }++ @Test+ void random_seedRoundsTowardsZero() {+ JsonNode statesVar = objectMapper.createObjectNode();+ assertEquals(evaluator.evaluate("{% $random(0) %}", statesVar).asDouble(),+ evaluator.evaluate("{% $random(0.9) %}", statesVar).asDouble());+ }++ @Test+ void random_surplusArgumentRaisesSignatureError() {+ JsonNode statesVar = objectMapper.createObjectNode();+ AslExecutor.FailStateException ex = assertThrows(AslExecutor.FailStateException.class,+ () -> evaluator.evaluate("{% $random(1, 2) %}", statesVar));+ assertTrue(ex.cause.contains("T0410"));+ }++ @Test+ void roundingGoesTowardsZeroNotDownwards() {+ // -1.7 becomes -1 on AWS, not -2. Flooring shifts every negative argument by one, which+ // is a whole extra element at the head of the range.+ JsonNode statesVar = objectMapper.createObjectNode();+ assertEquals("[-1,0,1,2]", evaluator.evaluate("{% $range(-1.7, 2, 1) %}", statesVar).toString());+ assertEquals("[-2,-1,0]", evaluator.evaluate("{% $range(-2.9, 0, 1) %}", statesVar).toString());+ assertEquals("[5,4,3,2,1]", evaluator.evaluate("{% $range(5, 1, -1.5) %}", statesVar).toString());+ // -0.5 rounds to 0, which is undefined, while -2 stays negative and is an error.+ assertTrue(evaluator.evaluate("{% $partition([1,2,3,4], -0.5) %}", statesVar).isNull());+ }++ @Test+ void range_stepNearLongMaxTerminates() {+ // Walking with `v += step` and testing `v <= end` never terminates here: the addition+ // wraps and lands back below the end on every pass.+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate(+ "{% $count($range(-9223372036854775808, 9223372036854775807, 9223372036854775807)) %}", statesVar);+ assertEquals(3, result.asInt());+ }++ @Test+ void hash_computesTheRemainingAlgorithmsAndHashesUtf8Bytes() {+ JsonNode statesVar = objectMapper.createObjectNode();+ assertEquals("3519fe5ad2c596efe3e276a6f351b8fc0b03db861782490d45f7598ebd0ab5fd"+ + "5520ed102f38c4a5ec834e98668035fc",+ evaluator.evaluate("{% $hash('Hello', 'SHA-384') %}", statesVar).asText());+ assertEquals("3615f80c9d293ed7402687f94b22d58e529b8cc7916f8fac7fddf7fbd5af4cf7"+ + "77d3d795a7a00a16bf7e7f3fb9561ee9baae480da9fe7a18769e71886b03f315",+ evaluator.evaluate("{% $hash('Hello', 'SHA-512') %}", statesVar).asText());+ // A non-ASCII character is hashed as UTF-8, not as the platform charset.+ assertEquals("94e9342ecbb1458b6043ecd3bfcbc192",+ evaluator.evaluate("{% $hash('ñ', 'MD5') %}", statesVar).asText());+ }++ @Test+ void hash_missingAlgorithmIsUndefinedButNonStringOneIsASignatureError() {+ JsonNode statesVar = objectMapper.createObjectNode();+ assertTrue(evaluator.evaluate("{% $hash('a') %}", statesVar).isNull());+ AslExecutor.FailStateException ex = assertThrows(AslExecutor.FailStateException.class,+ () -> evaluator.evaluate("{% $hash('a', 5) %}", statesVar));+ assertTrue(ex.cause.contains("T0410"));+ }++ @Test+ void parse_keepsFieldOrder() {+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $parse('{\"b\":1,\"a\":2}') %}", statesVar);+ assertEquals("{\"b\":1,\"a\":2}", result.toString());+ }++ @Test+ void parse_keepsAnIntegerExactWhileItFitsInALong() {+ // Reading every integer as a long regardless of width is what turns a number larger than+ // a long negative. AWS switches to exponent notation at the same boundary.+ JsonNode statesVar = objectMapper.createObjectNode();+ assertEquals("9223372036854775807",+ evaluator.evaluate("{% $parse('{\"n\":9223372036854775807}').n %}", statesVar).toString());+ assertEquals(9.223372036854776E18,+ evaluator.evaluate("{% $parse('{\"n\":9223372036854775808}').n %}", statesVar).asDouble());+ assertEquals(1.2345678901234568E29,+ evaluator.evaluate("{% $parse('123456789012345678901234567890') %}", statesVar).asDouble());+ }++ @Test+ void parse_dropsATrailingZeroOnAnIntegerValuedNumber() {+ JsonNode statesVar = objectMapper.createObjectNode();+ assertEquals("1", evaluator.evaluate("{% $parse('1.0') %}", statesVar).toString());+ assertEquals("100", evaluator.evaluate("{% $parse('1e2') %}", statesVar).toString());+ assertEquals("1.5", evaluator.evaluate("{% $parse('1.5') %}", statesVar).toString());+ }++ @Test+ void parse_rejectsJsonAwsRejects() {+ JsonNode statesVar = objectMapper.createObjectNode();+ // An empty body, a second document after the first, a repeated key and a number too large+ // for a double are all D3137 on AWS. A lenient parser turns the first into "" and the+ // second into a silent success on a truncated payload.+ for (String json : new String[]{"''", "' '", "'{\"a\":1}{\"b\":2}'", "'[1,2] [3,4]'",+ "'{\"a\":1,\"a\":2}'", "'1e400'"}) {+ AslExecutor.FailStateException ex = assertThrows(AslExecutor.FailStateException.class,+ () -> evaluator.evaluate("{% $parse(" + json + ") %}", statesVar),+ "expected $parse(" + json + ") to fail");+ assertTrue(ex.cause.contains("D3137: Invalid JSON"),+ "wrong cause for $parse(" + json + "): " + ex.cause);+ }+ }++ @Test+ void surplusArgumentsRaiseASignatureError() {+ JsonNode statesVar = objectMapper.createObjectNode();+ for (String expression : new String[]{"$parse('{}', 'x')", "$partition([1,2,3], 2, 'x')",+ "$range(1, 5, 1, 'x')", "$hash('a', 'MD5', 'x')"}) {+ AslExecutor.FailStateException ex = assertThrows(AslExecutor.FailStateException.class,+ () -> evaluator.evaluate("{% " + expression + " %}", statesVar),+ "expected " + expression + " to fail");+ assertTrue(ex.cause.contains("T0410"), "wrong code for " + expression + ": " + ex.cause);+ }+ }++ @Test+ void functionsAreUsableAsAValueInAHigherOrderCall() {+ // dashjoin dereferences the signature of a bound function unconditionally in $map and+ // friends, so a function bound without one throws a raw NullPointerException here.+ JsonNode statesVar = objectMapper.createObjectNode();+ JsonNode result = evaluator.evaluate("{% $map(['{\"a\":1}', '{\"a\":2}'], $parse).a %}", statesVar);+ assertEquals("[1,2]", result.toString());+ }}diff --git a/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsJsonataFunctionsIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsJsonataFunctionsIntegrationTest.javanew file mode 100644index 0000000000..a30c07f289--- /dev/null+++ b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/StepFunctionsJsonataFunctionsIntegrationTest.java@@ -0,0 +1,317 @@+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.Test;++import static io.restassured.RestAssured.given;+import static org.junit.jupiter.api.Assertions.assertEquals;+import static org.junit.jupiter.api.Assertions.assertTrue;+import static org.junit.jupiter.api.Assertions.fail;++/**+ * The six functions the Step Functions JSONata dialect adds on top of the JSONata language:+ * $parse, $partition, $range, $hash, $random and $uuid. Every expected value here was captured+ * from real AWS. Unit coverage of the edge cases lives in {@link JsonataEvaluatorTest}; these+ * cases run the functions through CreateStateMachine and StartExecution, which is how a state+ * machine reaches them.+ */+@QuarkusTest+class StepFunctionsJsonataFunctionsIntegrationTest {++ 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 final ObjectMapper objectMapper = new ObjectMapper();++ @BeforeAll+ static void configureRestAssured() {+ RestAssuredJsonUtils.configureAwsContentTypes();+ }++ @Test+ void parseDeserializesAJsonStringAndNavigatesTheResult() throws Exception {+ // The dominant real-world shape: a nested execution returns its Output as a JSON string,+ // and the caller reads a field off it. AWS disables $eval, so $parse is the only way in.+ String definition = """+ {+ "QueryLanguage": "JSONata",+ "StartAt": "Read",+ "States": {+ "Read": {+ "Type": "Pass",+ "Output": {+ "amount": "{% $parse($states.input.body).detail.amount %}",+ "currency": "{% $parse($states.input.body).detail.currency %}"+ },+ "End": true+ }+ }+ }+ """;++ String smArn = createStateMachine("jsonata-parse", definition);+ String input = "{\"body\": \"{\\\"detail\\\":{\\\"amount\\\":1250,\\\"currency\\\":\\\"ARS\\\"}}\"}";+ JsonNode output = objectMapper.readTree(waitForExecution(startExecution(smArn, input)));++ assertEquals(1250, output.get("amount").asInt());+ assertEquals("ARS", output.get("currency").asText());+ }++ @Test+ void partitionSplitsAnArrayIntoChunksWithAShorterLastChunk() throws Exception {+ String definition = """+ {+ "QueryLanguage": "JSONata",+ "StartAt": "Split",+ "States": {+ "Split": {+ "Type": "Pass",+ "Output": {+ "chunks": "{% $partition([1, 2, 3, 4, 5], 2) %}"+ },+ "End": true+ }+ }+ }+ """;++ String smArn = createStateMachine("jsonata-partition", definition);+ JsonNode output = objectMapper.readTree(waitForExecution(startExecution(smArn, "{}")));++ assertEquals("[[1,2],[3,4],[5]]", output.get("chunks").toString());+ }++ @Test+ void rangeIncludesTheEndValueWhenTheStepLandsOnIt() throws Exception {+ String definition = """+ {+ "QueryLanguage": "JSONata",+ "StartAt": "Generate",+ "States": {+ "Generate": {+ "Type": "Pass",+ "Output": {+ "even": "{% $range(0, 6, 2) %}",+ "descending": "{% $range(3, 1, -1) %}"+ },+ "End": true+ }+ }+ }+ """;++ String smArn = createStateMachine("jsonata-range", definition);+ JsonNode output = objectMapper.readTree(waitForExecution(startExecution(smArn, "{}")));++ assertEquals("[0,2,4,6]", output.get("even").toString());+ assertEquals("[3,2,1]", output.get("descending").toString());+ }++ @Test+ void hashComputesTheHexDigestForEachSupportedAlgorithm() throws Exception {+ String definition = """+ {+ "QueryLanguage": "JSONata",+ "StartAt": "Digest",+ "States": {+ "Digest": {+ "Type": "Pass",+ "Output": {+ "md5": "{% $hash('input', 'MD5') %}",+ "sha1": "{% $hash('input', 'SHA-1') %}",+ "sha256": "{% $hash('input', 'SHA-256') %}"+ },+ "End": true+ }+ }+ }+ """;++ String smArn = createStateMachine("jsonata-hash", definition);+ JsonNode output = objectMapper.readTree(waitForExecution(startExecution(smArn, "{}")));++ assertEquals("a43c1b0aa53a0c908810c06ab1ff3967", output.get("md5").asText());+ assertEquals("140f86aae51ab9e1cda9b4254fe98a74eb54c1a1", output.get("sha1").asText());+ assertEquals("c96c6d5be8d08a12e7b5cdc1b207fa6b2430974c86803d8891675e76fd992c20",+ output.get("sha256").asText());+ }++ @Test+ void uuidGeneratesACanonicalV4Uuid() throws Exception {+ String definition = """+ {+ "QueryLanguage": "JSONata",+ "StartAt": "Mint",+ "States": {+ "Mint": {+ "Type": "Pass",+ "Output": {+ "first": "{% $uuid() %}",+ "second": "{% $uuid() %}"+ },+ "End": true+ }+ }+ }+ """;++ String smArn = createStateMachine("jsonata-uuid", definition);+ JsonNode output = objectMapper.readTree(waitForExecution(startExecution(smArn, "{}")));++ String first = output.get("first").asText();+ String second = output.get("second").asText();+ assertTrue(first.matches("[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"),+ "not a canonical v4 UUID: " + first);+ assertTrue(!first.equals(second), "two calls returned the same UUID: " + first);+ }++ @Test+ void randomAcceptsTheSeedThatJsonatasOwnRandomRejects() throws Exception {+ String definition = """+ {+ "QueryLanguage": "JSONata",+ "StartAt": "Draw",+ "States": {+ "Draw": {+ "Type": "Pass",+ "Output": {+ "seeded": "{% $random(42) %}",+ "unseeded": "{% $random() %}"+ },+ "End": true+ }+ }+ }+ """;++ String smArn = createStateMachine("jsonata-random", definition);+ JsonNode output = objectMapper.readTree(waitForExecution(startExecution(smArn, "{}")));++ assertEquals(0.7275636800328681, output.get("seeded").asDouble());+ assertTrue(output.get("unseeded").asDouble() >= 0 && output.get("unseeded").asDouble() < 1,+ "unseeded draw outside [0, 1): " + output.get("unseeded"));+ }++ @Test+ void anUnsupportedHashAlgorithmFailsTheExecution() throws Exception {+ String definition = """+ {+ "QueryLanguage": "JSONata",+ "StartAt": "Digest",+ "States": {+ "Digest": {+ "Type": "Pass",+ "Output": {+ "digest": "{% $hash('input', 'SHA-9') %}"+ },+ "End": true+ }+ }+ }+ """;++ String smArn = createStateMachine("jsonata-hash-unsupported", definition);+ Response resp = waitForExecutionFailure(startExecution(smArn, "{}"));++ assertEquals("States.QueryEvaluationError", resp.jsonPath().getString("error"));+ assertTrue(resp.jsonPath().getString("cause").contains("SHA-9"),+ "cause does not name the rejected algorithm: " + resp.jsonPath().getString("cause"));+ }++ // ---- helpers ----++ private String createStateMachine(String name, String definition) {+ Response resp = given()+ .header("X-Amz-Target", "AWSStepFunctions.CreateStateMachine")+ .contentType(SFN_CONTENT_TYPE)+ .body(String.format("""+ {+ "name": "%s",+ "definition": %s,+ "roleArn": "%s"+ }+ """, name, quote(definition), ROLE_ARN))+ .when()+ .post("/");+ resp.then().statusCode(200);+ return resp.jsonPath().getString("stateMachineArn");+ }++ private String startExecution(String smArn, String input) {+ Response resp = given()+ .header("X-Amz-Target", "AWSStepFunctions.StartExecution")+ .contentType(SFN_CONTENT_TYPE)+ .body(String.format("""+ {+ "stateMachineArn": "%s",+ "input": %s+ }+ """, smArn, quote(input)))+ .when()+ .post("/");+ resp.then().statusCode(200);+ return resp.jsonPath().getString("executionArn");+ }++ private String waitForExecution(String execArn) throws InterruptedException {+ for (int i = 0; i < 50; i++) {+ Response resp = describeExecution(execArn);+ String status = resp.jsonPath().getString("status");+ if ("SUCCEEDED".equals(status)) {+ return resp.jsonPath().getString("output");+ }+ if ("FAILED".equals(status) || "ABORTED".equals(status)) {+ fail("Execution " + status + ": " + resp.body().asString());+ }+ Thread.sleep(100);+ }+ fail("Execution did not complete within timeout");+ return null;+ }++ private Response waitForExecutionFailure(String execArn) throws InterruptedException {+ for (int i = 0; i < 50; i++) {+ Response resp = describeExecution(execArn);+ String status = resp.jsonPath().getString("status");+ if ("FAILED".equals(status) || "ABORTED".equals(status)) {+ return resp;+ }+ if ("SUCCEEDED".equals(status)) {+ fail("Execution SUCCEEDED: " + resp.body().asString());+ }+ Thread.sleep(100);+ }+ fail("Execution did not fail within timeout");+ return null;+ }++ private Response describeExecution(String execArn) {+ return given()+ .header("X-Amz-Target", "AWSStepFunctions.DescribeExecution")+ .contentType(SFN_CONTENT_TYPE)+ .body(String.format("""+ { "executionArn": "%s" }+ """, execArn))+ .when()+ .post("/");+ }++ /**+ * JSON-encode a string value (escape and wrap in quotes) for embedding+ * inside a JSON body where the field expects a string.+ */+ private static String quote(String raw) {+ return "\"" + raw+ .replace("\\", "\\\\")+ .replace("\"", "\\\"")+ .replace("\n", "\\n")+ .replace("\r", "\\r")+ .replace("\t", "\\t")+ + "\"";+ }+}