Light, fluffy, and always free - The AWS Local Emulator alternative
feat(sfn): encode HTTP Task object bodies as form data (#6010)
Aniket Shuklaf8ab55f319ea
diff --git a/docs/services/step-functions.md b/docs/services/step-functions.mdindex 03a4aeddcc..2ed357ae21 100644--- a/docs/services/step-functions.md+++ b/docs/services/step-functions.md@@ -722,6 +722,23 @@ Local, the execution starts and fails with `States.Runtime` only if the state thit is entered. This keeps a generated mock file usable when the collection it was builtfrom is empty and the state is never reached.+## HTTP Task request bodies++For `arn:aws:states:::http:invoke`, `Transform.RequestBodyEncoding: URL_ENCODED` sends+an object body as form data. Set `Headers.Content-Type` to+`application/x-www-form-urlencoded`. Nested objects use bracketed keys, and text is+percent-encoded as UTF-8. `RequestEncodingOptions.ArrayFormat` supports `INDICES`+(the default), `REPEAT`, `COMMAS`, and `BRACKETS`, following the+[AWS HTTP Task encoding options](https://docs.aws.amazon.com/step-functions/latest/dg/call-https-apis.html#connect-http-task-url-encoding).+`NONE` keeps the JSON-body path unchanged.++Floci currently supports object roots and scalar `COMMAS` arrays. Non-object roots+(other than an absent or null body) and `COMMAS` arrays containing objects or arrays+fail explicitly instead of being silently coerced. These are Floci limitations,+not documented AWS restrictions; their exact AWS behavior has not been verified.+EventBridge connection lookup and connection-level parameter merging are not+implemented by the HTTP Task.+## Executions abandoned by a restartAn execution runs in the Floci process. When Floci restarts while an execution is `RUNNING`,diff --git a/src/main/java/io/github/hectorvent/floci/services/stepfunctions/AslExecutor.java b/src/main/java/io/github/hectorvent/floci/services/stepfunctions/AslExecutor.javaindex f3f42fdb91..73be17bada 100644--- a/src/main/java/io/github/hectorvent/floci/services/stepfunctions/AslExecutor.java+++ b/src/main/java/io/github/hectorvent/floci/services/stepfunctions/AslExecutor.java@@ -4784,7 +4784,8 @@ public class AslExecutor {validateConnectionArn(input);validateHttpHeaders(headers);- HttpRequestPayload requestPayload = requestPayload(requestBody, requestBodyEncoding);+ HttpRequestPayload requestPayload = requestPayload(requestBody, requestBodyEncoding,+ input.path("Transform").path("RequestEncodingOptions"));MultiMap requestHeaders = requestHeaders(headers, requestPayload.contentType());MultiMap requestQueryParameters = queryParameters(queryParameters);@@ -4814,9 +4815,6 @@ public class AslExecutor {}private HttpResponse<Buffer> sendHttpRequest(HttpRequest<Buffer> request, HttpRequestPayload payload) throws NoStackTraceTimeoutException {- if (payload.form() != null) {- return request.sendFormAndAwait(payload.form());- }if (payload.body() != null) {return request.sendBufferAndAwait(payload.body());}@@ -4910,19 +4908,22 @@ public class AslExecutor {}}- private HttpRequestPayload requestPayload(JsonNode requestBody, String requestBodyEncoding) {+ private HttpRequestPayload requestPayload(JsonNode requestBody, String requestBodyEncoding, JsonNode options) {if ("URL_ENCODED".equalsIgnoreCase(requestBodyEncoding)) {- // TODO: Implement Transform.RequestBodyEncoding URL_ENCODED with AWS-compatible array formats.- throw new FailStateException("States.TaskFailed", "URL-encoded request bodies are not supported yet");+ try {+ return new HttpRequestPayload(Buffer.buffer(HttpTaskFormEncoder.encode(requestBody, options)),+ "application/x-www-form-urlencoded");+ } catch (IllegalArgumentException e) {+ throw new FailStateException("States.TaskFailed", e.getMessage());+ }} else if ("NONE".equalsIgnoreCase(requestBodyEncoding)) {try {if (requestBody.isMissingNode() || requestBody.isNull()) {- return new HttpRequestPayload(null, null, null);+ return new HttpRequestPayload(null, null);}return new HttpRequestPayload(Buffer.buffer(objectMapper.writeValueAsString(requestBody)),- null,"application/json");} catch (Exception e) {throw new FailStateException("States.TaskFailed",@@ -4934,7 +4935,7 @@ public class AslExecutor {}}- private record HttpRequestPayload(Buffer body, MultiMap form, String contentType) {+ private record HttpRequestPayload(Buffer body, String contentType) {}private record HttpTaskResponse(diff --git a/src/main/java/io/github/hectorvent/floci/services/stepfunctions/HttpTaskFormEncoder.java b/src/main/java/io/github/hectorvent/floci/services/stepfunctions/HttpTaskFormEncoder.javanew file mode 100644index 0000000000..25ff932667--- /dev/null+++ b/src/main/java/io/github/hectorvent/floci/services/stepfunctions/HttpTaskFormEncoder.java@@ -0,0 +1,79 @@+package io.github.hectorvent.floci.services.stepfunctions;++import com.fasterxml.jackson.databind.JsonNode;+import io.github.hectorvent.floci.core.common.auth.SigV4Canonicalization;++import java.util.ArrayList;+import java.util.List;+import java.util.StringJoiner;++/** Object-body and scalar-array encodings documented for Step Functions HTTP Tasks. */+final class HttpTaskFormEncoder {++ private enum ArrayFormat { INDICES, REPEAT, COMMAS, BRACKETS }++ private HttpTaskFormEncoder() {+ }++ // https://docs.aws.amazon.com/step-functions/latest/dg/call-https-apis.html#connect-http-task-url-encoding+ static String encode(JsonNode body, JsonNode options) {+ if (!options.isMissingNode() && !options.isObject()) {+ throw new IllegalArgumentException("RequestEncodingOptions must be a JSON object");+ }+ JsonNode configuredFormat = options.path("ArrayFormat");+ ArrayFormat format = ArrayFormat.INDICES;+ if (!configuredFormat.isMissingNode()) {+ if (!configuredFormat.isTextual()) {+ throw new IllegalArgumentException("ArrayFormat must be a supported string value");+ }+ try {+ format = ArrayFormat.valueOf(configuredFormat.textValue());+ } catch (IllegalArgumentException e) {+ throw new IllegalArgumentException("Unsupported ArrayFormat: " + configuredFormat.textValue());+ }+ }+ if (body.isMissingNode() || body.isNull()) {+ return "";+ }+ if (!body.isObject()) {+ throw new IllegalArgumentException("Floci URL_ENCODED request bodies currently require a JSON object");+ }+ List<String> pairs = new ArrayList<>();+ ArrayFormat selected = format;+ body.fields().forEachRemaining(entry -> append(pairs, entry.getKey(), entry.getValue(), selected));+ return String.join("&", pairs);+ }++ private static void append(List<String> pairs, String key, JsonNode value, ArrayFormat format) {+ if (value.isObject()) {+ value.fields().forEachRemaining(entry ->+ append(pairs, key + "[" + entry.getKey() + "]", entry.getValue(), format));+ } else if (value.isArray()) {+ if (value.isEmpty()) {+ return;+ }+ if (format == ArrayFormat.COMMAS) {+ StringJoiner values = new StringJoiner(",");+ for (JsonNode element : value) {+ if (element.isContainerNode()) {+ throw new IllegalArgumentException("Floci COMMAS arrays currently require scalar values");+ }+ values.add(SigV4Canonicalization.uriEncode(element.isNull() ? "" : element.asText()));+ }+ pairs.add(SigV4Canonicalization.uriEncode(key) + "=" + values);+ return;+ }+ for (int index = 0; index < value.size(); index++) {+ String arrayKey = switch (format) {+ case INDICES -> key + "[" + index + "]";+ case BRACKETS -> key + "[]";+ default -> key;+ };+ append(pairs, arrayKey, value.get(index), format);+ }+ } else {+ pairs.add(SigV4Canonicalization.uriEncode(key) + "="+ + SigV4Canonicalization.uriEncode(value.isNull() ? "" : value.asText()));+ }+ }+}diff --git a/src/test/java/io/github/hectorvent/floci/services/stepfunctions/AslExecutorHttpInvokeTest.java b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/AslExecutorHttpInvokeTest.javaindex e745706e68..066be24ecd 100644--- a/src/test/java/io/github/hectorvent/floci/services/stepfunctions/AslExecutorHttpInvokeTest.java+++ b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/AslExecutorHttpInvokeTest.java@@ -21,6 +21,9 @@ import jakarta.inject.Inject;import org.junit.jupiter.api.AfterEach;import org.junit.jupiter.api.BeforeEach;import org.junit.jupiter.api.Test;+import org.junit.jupiter.params.ParameterizedTest;+import org.junit.jupiter.params.provider.CsvSource;+import org.junit.jupiter.params.provider.ValueSource;import java.time.Duration;import java.util.ArrayList;@@ -146,7 +149,7 @@ class AslExecutorHttpInvokeTest {.endAndForget(Buffer.newInstance(JsonObject.of("ok", "false").toBuffer())));server.requestHandler(router)- .listenAndAwait(0);+ .listenAndAwait(0, "127.0.0.1");baseUrl = "http://127.0.0.1:" + server.actualPort();executor = AslExecutorFixture.builder()@@ -428,7 +431,7 @@ class AslExecutorHttpInvokeTest {}@Test- void formTransformationIsUnsupported() {+ void unknownBodyTransformationFailsBeforeSending() {Execution execution = run("""{"StartAt": "CallHttp",@@ -444,7 +447,7 @@ class AslExecutorHttpInvokeTest {"ConnectionArn": "%s"},"Transform": {- "RequestBodyEncoding": "URL_ENCODED",+ "RequestBodyEncoding": "INVALID","RequestEncodingOptions": {"ArrayFormat": "COMMAS"}@@ -464,7 +467,64 @@ class AslExecutorHttpInvokeTest {assertEquals("FAILED", execution.getStatus());assertEquals("States.TaskFailed", execution.getError());- assertThat(execution.getCause(), startsWith("URL-encoded request bodies are not supported yet"));+ assertThat(execution.getCause(), startsWith("Unsupported body transformer: INVALID"));+ assertEquals(0, receivedRequests.size());+ }++ @ParameterizedTest+ @CsvSource(delimiter = '|', value = {+ "INDICES | colors%5B0%5D=red%20blue&colors%5B1%5D=a%26b&colors%5B2%5D=caf%C3%A9",+ "REPEAT | colors=red%20blue&colors=a%26b&colors=caf%C3%A9",+ "COMMAS | colors=red%20blue,a%26b,caf%C3%A9",+ "BRACKETS | colors%5B%5D=red%20blue&colors%5B%5D=a%26b&colors%5B%5D=caf%C3%A9"+ })+ void formTransformationSendsTheDocumentedArrayFormats(String format, String expected) {+ Execution execution = runForm("{\"colors\":[\"red blue\",\"a&b\",\"café\"]}",+ "{\"ArrayFormat\":\"" + format + "\"}");++ assertEquals("SUCCEEDED", execution.getStatus(), execution.getCause());+ RecordedRequest request = onlyRequest();+ assertEquals("POST", request.method());+ assertEquals("application/x-www-form-urlencoded", request.firstHeader("Content-Type"));+ assertEquals(expected, request.body());+ }++ @Test+ void formTransformationDefaultsToIndicesAndEncodesNestedObjectsAndScalars() {+ Execution execution = runForm("""+ {"customer":"cust-123","metadata":{"order_details":"monthly report"},+ "symbols":"a&b=c+%","enabled":true,"count":3,"empty":"","nothing":null,+ "items":["one","two"]}+ """, "{}");++ assertEquals("SUCCEEDED", execution.getStatus(), execution.getCause());+ assertEquals("customer=cust-123&metadata%5Border_details%5D=monthly%20report"+ + "&symbols=a%26b%3Dc%2B%25&enabled=true&count=3&empty=¬hing="+ + "&items%5B0%5D=one&items%5B1%5D=two", onlyRequest().body());+ }++ @ParameterizedTest+ @ValueSource(strings = {"{\"ArrayFormat\":\"INVALID\"}", "{\"ArrayFormat\":null}",+ "{\"ArrayFormat\":{}}", "[]"})+ void malformedFormOptionsFailBeforeSending(String options) {+ Execution execution = runForm("{\"value\":1}", options);++ assertEquals("FAILED", execution.getStatus());+ assertEquals("States.TaskFailed", execution.getError());+ assertEquals(0, receivedRequests.size());+ }++ private Execution runForm(String body, String options) {+ return run("""+ {"StartAt":"CallHttp","States":{"CallHttp":{"Type":"Task",+ "Resource":"arn:aws:states:::http:invoke","Parameters":{+ "ApiEndpoint":"%s/text","Method":"POST",+ "Authentication":{"ConnectionArn":"%s"},+ "Headers":{"Content-Type":"application/x-www-form-urlencoded"},+ "RequestBody.$":"$.body",+ "Transform":{"RequestBodyEncoding":"URL_ENCODED","RequestEncodingOptions":%s}+ },"End":true}}}+ """.formatted(baseUrl, CONNECTION_ARN, options), "{\"body\":" + body + "}");}private Execution run(String definition, String input) {diff --git a/src/test/java/io/github/hectorvent/floci/services/stepfunctions/HttpTaskFormEncoderTest.java b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/HttpTaskFormEncoderTest.javanew file mode 100644index 0000000000..904a57e855--- /dev/null+++ b/src/test/java/io/github/hectorvent/floci/services/stepfunctions/HttpTaskFormEncoderTest.java@@ -0,0 +1,75 @@+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.MissingNode;+import org.junit.jupiter.api.Test;+import org.junit.jupiter.params.ParameterizedTest;+import org.junit.jupiter.params.provider.ValueSource;++import static org.junit.jupiter.api.Assertions.assertEquals;+import static org.junit.jupiter.api.Assertions.assertThrows;++class HttpTaskFormEncoderTest {+ private final ObjectMapper mapper = new ObjectMapper();++ @Test+ void nestedArrayObjectsUseBracketPathsWithoutMutatingTheInput() throws Exception {+ JsonNode body = mapper.readTree("{\"items\":[{\"name\":\"café\",\"flags\":[true,false]}]}");+ JsonNode original = body.deepCopy();++ assertEquals("items%5B0%5D%5Bname%5D=caf%C3%A9&items%5B0%5D%5Bflags%5D%5B0%5D=true"+ + "&items%5B0%5D%5Bflags%5D%5B1%5D=false",+ HttpTaskFormEncoder.encode(body, MissingNode.getInstance()));+ assertEquals(original, body);+ }++ @Test+ void commaSeparatorsStayDistinctFromCommasInsideValues() throws Exception {+ JsonNode options = mapper.readTree("{\"ArrayFormat\":\"COMMAS\"}");+ assertEquals("v=a%2Cb,c", HttpTaskFormEncoder.encode(mapper.readTree("{\"v\":[\"a,b\",\"c\"]}"), options));+ assertEquals("v=a,b%2Cc", HttpTaskFormEncoder.encode(mapper.readTree("{\"v\":[\"a\",\"b,c\"]}"), options));+ }++ @Test+ void namesAndValuesCannotInjectAdditionalFields() throws Exception {+ assertEquals("a%26b%3Dc=%2B%25%26%3D%20%2A~%0D%0A",+ HttpTaskFormEncoder.encode(mapper.readTree("{\"a&b=c\":\"+%&= *~\\r\\n\"}"),+ MissingNode.getInstance()));+ }++ @Test+ void emptyContainersAreOmittedWhileNullAndEmptyScalarsAreKept() throws Exception {+ assertEquals("null=&empty=", HttpTaskFormEncoder.encode(+ mapper.readTree("{\"array\":[],\"object\":{},\"null\":null,\"empty\":\"\"}"),+ MissingNode.getInstance()));+ assertEquals("", HttpTaskFormEncoder.encode(mapper.nullNode(), MissingNode.getInstance()));+ assertEquals("", HttpTaskFormEncoder.encode(MissingNode.getInstance(), MissingNode.getInstance()));+ }++ @ParameterizedTest+ @ValueSource(strings = {"null", "[]", "1", "\"INDICES\"", "{\"ArrayFormat\":null}",+ "{\"ArrayFormat\":{}}", "{\"ArrayFormat\":[]}", "{\"ArrayFormat\":7}",+ "{\"ArrayFormat\":\"INVALID\"}"})+ void malformedOptionsDoNotSilentlySelectTheDefault(String options) throws Exception {+ JsonNode parsed = mapper.readTree(options);+ assertThrows(IllegalArgumentException.class,+ () -> HttpTaskFormEncoder.encode(mapper.createObjectNode(), parsed));+ }++ @ParameterizedTest+ @ValueSource(strings = {"\"text\"", "[]", "123", "true"})+ void unverifiedNonObjectRootBodiesRemainExplicitlyUnsupported(String body) throws Exception {+ JsonNode parsed = mapper.readTree(body);+ assertThrows(IllegalArgumentException.class,+ () -> HttpTaskFormEncoder.encode(parsed, MissingNode.getInstance()));+ }++ @ParameterizedTest+ @ValueSource(strings = {"{\"v\":[{}]}", "{\"v\":[[]]}"})+ void unverifiedCompoundCommaArraysAreNotSilentlyCoerced(String body) throws Exception {+ JsonNode parsed = mapper.readTree(body);+ JsonNode options = mapper.readTree("{\"ArrayFormat\":\"COMMAS\"}");+ assertThrows(IllegalArgumentException.class, () -> HttpTaskFormEncoder.encode(parsed, options));+ }+}