Light, fluffy, and always free - The AWS Local Emulator alternative
feat(ecs): implement ExecuteCommand (#4121)
Abhigyafcc89c0e8d5b
diff --git a/compatibility-tests/sdk-test-java/src/test/java/com/floci/test/EcsFargateTest.java b/compatibility-tests/sdk-test-java/src/test/java/com/floci/test/EcsFargateTest.javaindex bb1ed53c1c..ffc8829e3c 100644--- a/compatibility-tests/sdk-test-java/src/test/java/com/floci/test/EcsFargateTest.java+++ b/compatibility-tests/sdk-test-java/src/test/java/com/floci/test/EcsFargateTest.java@@ -27,6 +27,7 @@ import software.amazon.awssdk.services.ecs.model.DescribeTasksResponse;import software.amazon.awssdk.services.ecs.model.EcsException;import software.amazon.awssdk.services.ecs.model.KeyValuePair;import software.amazon.awssdk.services.ecs.model.EphemeralStorage;+import software.amazon.awssdk.services.ecs.model.ExecuteCommandRequest;import software.amazon.awssdk.services.ecs.model.LaunchType;import software.amazon.awssdk.services.ecs.model.NetworkConfiguration;import software.amazon.awssdk.services.ecs.model.NetworkMode;@@ -211,6 +212,37 @@ class EcsFargateTest {.cluster(clusterName).task(task.taskArn()).build());}+ @Test+ @Order(5)+ @DisplayName("ExecuteCommand - refused for a task that was not run with it enabled")+ void executeCommandRequiresTheTaskToHaveItEnabled() {+ Task plain = ecs.runTask(RunTaskRequest.builder()+ .cluster(clusterName)+ .taskDefinition(family)+ .launchType(LaunchType.FARGATE)+ .networkConfiguration(NetworkConfiguration.builder()+ .awsvpcConfiguration(AwsVpcConfiguration.builder()+ .subnets(subnetId)+ .build())+ .build())+ .build()).tasks().get(0);++ try {+ assertThatThrownBy(() -> ecs.executeCommand(ExecuteCommandRequest.builder()+ .cluster(clusterName)+ .task(plain.taskArn())+ .container("app")+ .command("/bin/sh")+ .interactive(true)+ .build()))+ .isInstanceOf(EcsException.class)+ .hasMessageContaining("execute command was not enabled");+ } finally {+ ecs.stopTask(StopTaskRequest.builder()+ .cluster(clusterName).task(plain.taskArn()).build());+ }+ }+@Test@Order(6)@DisplayName("DescribeClusters - include gates the optional members and statistics deserialize")diff --git a/docs/services/ecs.md b/docs/services/ecs.mdindex b15041d892..463433d29b 100644--- a/docs/services/ecs.md+++ b/docs/services/ecs.md@@ -194,6 +194,7 @@ cycles involving both volume inheritance and log routing are rejected before con| `ListTasks` | List task ARNs (filterable by cluster, family, service, status) || `UpdateTaskProtection` | Set scale-in protection for tasks || `GetTaskProtection` | Get current task protection state |+| `ExecuteCommand` | Open an ECS Exec session into a container (see [ECS Exec](#ecs-exec)) |### Fargate@@ -345,6 +346,33 @@ one, as on AWS. A container's `CreatedAt`, `StartedAt` and `FinishedAt` are Dockcontainer, read when it starts and again when it stops; a task that never reached a daemon, whichmeans `mock: true` or one restored from storage, reports the task's timestamps instead.+#### ECS Exec++`ExecuteCommand` opens a real shell in a task's container. The session must be `interactive`, which+is the only mode ECS supports. The task must belong to the cluster the request names, must be+`RUNNING`, must have been run with+`enableExecuteCommand`, and must have a container behind it, which means Docker mode:+a mock-mode task reports the `ExecuteCommandAgent` as running but has no runtime to exec into, and+`ExecuteCommand` answers `TargetNotConnectedException`.++The response carries a `session` with a `streamUrl` pointing at Floci's own data channel and a+single-use `tokenValue`, so the AWS CLI works as documented:++```bash+aws ecs execute-command --cluster my-cluster --task <task-arn> \+ --container app --interactive --command "/bin/sh" \+ --endpoint-url $AWS_ENDPOINT_URL+```++Floci plays the SSM agent's half of the Session Manager protocol on that channel (the binary+`AgentMessage` framing, the handshake, sequenced acknowledgements and terminal resizes) and bridges+it to a `docker exec` in the container. Deliberate limits:++- The command runs through `/bin/sh -c`, so an image without a shell cannot be exec'd into.+- Sessions are in memory, single use, and expire after five minutes if nobody connects.+- `ExecuteCommand` logging (the `executeCommandConfiguration` on a cluster, which sends session+ transcripts to S3 or CloudWatch) is not implemented.+### Services| Operation | Description |@@ -676,7 +704,7 @@ A task's `efsVolumeConfiguration` volumes are backed by shared local Docker volu### Mock mode-Set `FLOCI_SERVICES_ECS_MOCK=true` to run without Docker. In this mode tasks skip container launch and immediately transition to `RUNNING`, then to `STOPPED` when stopped. The task still reports a container per container definition and, for `awsvpc`, a real ENI, so a client reading `containers[]` or waiting on the task's address behaves as it does against AWS; nothing is running behind those containers, so no logs are streamed. This is the recommended mode for unit/integration tests and CI pipelines where Docker-in-Docker is unavailable.+Set `FLOCI_SERVICES_ECS_MOCK=true` to run without Docker. In this mode tasks skip container launch and immediately transition to `RUNNING`, then to `STOPPED` when stopped. The task still reports a container per container definition and, for `awsvpc`, a real ENI, so a client reading `containers[]` or waiting on the task's address behaves as it does against AWS; nothing is running behind those containers, so ECS Exec answers `TargetNotConnectedException` and no logs are streamed. This is the recommended mode for unit/integration tests and CI pipelines where Docker-in-Docker is unavailable.```yaml# docker-compose.yml — CI / test environmentdiff --git a/src/main/java/io/github/hectorvent/floci/services/ecs/EcsJsonHandler.java b/src/main/java/io/github/hectorvent/floci/services/ecs/EcsJsonHandler.javaindex 1e24b23636..a65f9da65f 100644--- a/src/main/java/io/github/hectorvent/floci/services/ecs/EcsJsonHandler.java+++ b/src/main/java/io/github/hectorvent/floci/services/ecs/EcsJsonHandler.java@@ -111,6 +111,7 @@ public class EcsJsonHandler {case "ListTasks" -> handleListTasks(request, region);case "UpdateTaskProtection" -> handleUpdateTaskProtection(request, region);case "GetTaskProtection" -> handleGetTaskProtection(request, region);+ case "ExecuteCommand" -> handleExecuteCommand(request, region);case "CreateService" -> handleCreateService(request, region);case "UpdateService" -> handleUpdateService(request, region);@@ -514,6 +515,31 @@ public class EcsJsonHandler {return Response.ok(resp).build();}+ private Response handleExecuteCommand(JsonNode req, String region) {+ String cluster = req.has("cluster") ? req.path("cluster").asText() : null;+ String task = req.path("task").asText();+ String container = req.hasNonNull("container") ? req.path("container").asText() : null;+ String command = req.path("command").asText(null);+ boolean interactive = req.path("interactive").asBoolean(false);++ EcsService.ExecuteCommandResult result =+ service.executeCommand(cluster, task, container, command, interactive, region);++ ObjectNode resp = objectMapper.createObjectNode();+ resp.put("clusterArn", result.task().getClusterArn());+ resp.put("taskArn", result.task().getTaskArn());+ resp.put("containerName", result.container().getName());+ if (result.container().getContainerArn() != null) {+ resp.put("containerArn", result.container().getContainerArn());+ }+ resp.put("interactive", interactive);+ ObjectNode session = resp.putObject("session");+ session.put("sessionId", result.session().sessionId());+ session.put("streamUrl", service.execStreamUrl(result.session()));+ session.put("tokenValue", result.session().tokenValue());+ return Response.ok(resp).build();+ }+// ── Services ──────────────────────────────────────────────────────────────/**diff --git a/src/main/java/io/github/hectorvent/floci/services/ecs/EcsService.java b/src/main/java/io/github/hectorvent/floci/services/ecs/EcsService.javaindex 3fa51b06fa..a0b5b94456 100644--- a/src/main/java/io/github/hectorvent/floci/services/ecs/EcsService.java+++ b/src/main/java/io/github/hectorvent/floci/services/ecs/EcsService.java@@ -13,6 +13,9 @@ import io.github.hectorvent.floci.core.storage.StorageBackedMap;import io.github.hectorvent.floci.core.storage.StorageFactory;import io.github.hectorvent.floci.services.ecs.container.EcsContainerManager;import io.github.hectorvent.floci.services.ecs.container.EcsTaskHandle;+import io.github.hectorvent.floci.services.ecs.exec.EcsExecChannelHandler;+import io.github.hectorvent.floci.services.ecs.exec.EcsExecSessionRegistry;+import io.github.hectorvent.floci.services.ecs.exec.ExecSession;import io.github.hectorvent.floci.services.ecs.model.Attribute;import io.github.hectorvent.floci.services.ecs.model.AwsVpcConfiguration;import io.github.hectorvent.floci.services.ecs.model.CapacityProvider;@@ -104,6 +107,7 @@ public class EcsService implements ContainerTeardown, ResourceProvider, Resettabprivate final EcsLoadBalancerRegistrar lbRegistrar;private final StorageFactory storageFactory;private final EcsEventPublisher eventPublisher;+ private final EcsExecSessionRegistry execSessions;private final boolean dockerMode;private final String baseUrl;// Replaced by afterReset() after a state reset, whose container teardown shuts this scheduler down.@@ -186,7 +190,8 @@ public class EcsService implements ContainerTeardown, ResourceProvider, Resettab@Injectpublic EcsService(RegionResolver regionResolver, EcsContainerManager containerManager,EmulatorConfig config, EcsLoadBalancerRegistrar lbRegistrar,- StorageFactory storageFactory, EcsEventPublisher eventPublisher) {+ StorageFactory storageFactory, EcsEventPublisher eventPublisher,+ EcsExecSessionRegistry execSessions) {this.regionResolver = regionResolver;this.containerManager = containerManager;this.dockerMode = !config.services().ecs().mock();@@ -194,6 +199,15 @@ public class EcsService implements ContainerTeardown, ResourceProvider, Resettabthis.lbRegistrar = lbRegistrar;this.storageFactory = storageFactory;this.eventPublisher = eventPublisher;+ this.execSessions = execSessions;+ }++ /** With an exec session registry of its own, for callers that assemble the service without CDI. */+ public EcsService(RegionResolver regionResolver, EcsContainerManager containerManager,+ EmulatorConfig config, EcsLoadBalancerRegistrar lbRegistrar,+ StorageFactory storageFactory, EcsEventPublisher eventPublisher) {+ this(regionResolver, containerManager, config, lbRegistrar, storageFactory, eventPublisher,+ new EcsExecSessionRegistry());}@PostConstruct@@ -1746,6 +1760,91 @@ public class EcsService implements ContainerTeardown, ResourceProvider, Resettab}}+ // ── ECS Exec ──────────────────────────────────────────────────────────────++ /** The resolved target of an {@code ExecuteCommand}, with the session the client connects to. */+ public record ExecuteCommandResult(EcsTask task, Container container, ExecSession session) {}++ /**+ * Opens an ECS Exec session against one of a task's containers.+ *+ * <p>The gate is the same as AWS's: the task must be running with execute-command enabled, and+ * the container must actually be there to exec into. The returned session carries a stream URL+ * and a single-use token, which {@code session-manager-plugin} then uses to open the data+ * channel.+ */+ public ExecuteCommandResult executeCommand(String clusterRef, String taskRef, String containerName,+ String command, boolean interactive, String region) {+ if (command == null || command.isBlank()) {+ throw new AwsException("InvalidParameterException",+ "The command cannot be empty.", 400);+ }+ // ECS only ever opens interactive sessions, so a request that asks for anything else is+ // asking for something the API cannot do.+ if (!interactive) {+ throw new AwsException("InvalidParameterException",+ "Amazon ECS only supports initiating interactive sessions, so you must specify "+ + "true for the interactive parameter.", 400);+ }+ EcsCluster cluster = resolveClusterOrDefault(clusterRef, region);+ EcsTask task = resolveTaskOrThrow(taskRef, region);+ if (!cluster.getClusterArn().equals(task.getClusterArn())) {+ throw new AwsException("InvalidParameterException",+ "The task " + task.getTaskArn() + " is not part of the cluster "+ + cluster.getClusterArn() + ".", 400);+ }+ if (!TaskStatus.RUNNING.name().equals(task.getLastStatus())) {+ throw new AwsException("TargetNotConnectedException",+ "The execute command failed because the task is not running.", 400);+ }+ if (!task.isEnableExecuteCommand()) {+ throw new AwsException("InvalidParameterException",+ "The execute command failed because execute command was not enabled when the task "+ + "was run or the execute command agent isn't running. Wait and try again "+ + "or run a new task with execute command enabled and try again.", 400);+ }+ Container container = resolveExecContainer(task, containerName);+ if (container.getRuntimeId() == null || container.getRuntimeId().isBlank()) {+ throw new AwsException("TargetNotConnectedException",+ "The execute command failed because the execute command agent is not running in "+ + "container " + container.getName() + ".", 400);+ }+ ExecSession session = execSessions.create(task.getTaskArn(), task.getClusterArn(),+ container.getName(), container.getContainerArn(), container.getRuntimeId(),+ List.of("/bin/sh", "-c", command), interactive);+ LOG.infov("Opened an ECS Exec session on {0} container {1}", task.getTaskArn(), container.getName());+ return new ExecuteCommandResult(task, container, session);+ }++ private static Container resolveExecContainer(EcsTask task, String containerName) {+ List<Container> containers = task.getContainers() != null ? task.getContainers() : List.of();+ if (containers.isEmpty()) {+ throw new AwsException("TargetNotConnectedException",+ "The execute command failed because the task has no running containers.", 400);+ }+ if (containerName == null || containerName.isBlank()) {+ if (containers.size() > 1) {+ throw new AwsException("InvalidParameterException",+ "The task has more than one container, so the container to run the command "+ + "in must be named.", 400);+ }+ return containers.getFirst();+ }+ return containers.stream()+ .filter(container -> containerName.equals(container.getName()))+ .findFirst()+ .orElseThrow(() -> new AwsException("InvalidParameterException",+ "The container " + containerName + " is not part of the task.", 400));+ }++ /** The {@code ws://} URL a client opens for an exec session's data channel. */+ public String execStreamUrl(ExecSession session) {+ String websocketBase = baseUrl.startsWith("https://")+ ? "wss://" + baseUrl.substring("https://".length())+ : "ws://" + baseUrl.substring(baseUrl.indexOf("://") + 3);+ return websocketBase + EcsExecChannelHandler.CHANNEL_PATH_PREFIX + session.sessionId();+ }+/** A container reached through the task metadata endpoint, with the task it belongs to. */public record MetadataTarget(EcsTask task, Container container, TaskDefinition taskDefinition) {}diff --git a/src/main/java/io/github/hectorvent/floci/services/ecs/exec/AgentMessage.java b/src/main/java/io/github/hectorvent/floci/services/ecs/exec/AgentMessage.javanew file mode 100644index 0000000000..de57803602--- /dev/null+++ b/src/main/java/io/github/hectorvent/floci/services/ecs/exec/AgentMessage.java@@ -0,0 +1,136 @@+package io.github.hectorvent.floci.services.ecs.exec;++import java.nio.ByteBuffer;+import java.nio.charset.StandardCharsets;+import java.security.MessageDigest;+import java.security.NoSuchAlgorithmException;+import java.util.Arrays;+import java.util.UUID;++/**+ * One frame of the Session Manager data channel, the binary envelope+ * {@code session-manager-plugin} exchanges with the SSM agent over the WebSocket.+ *+ * <p>The layout is fixed: a 116 byte header (whose own length is the first field, excluding the+ * trailing payload length) followed by the payload.+ *+ * <pre>+ * 0 header length int32 (116)+ * 4 message type 32 bytes, space padded+ * 36 schema version uint32+ * 40 created date uint64, epoch millis+ * 48 sequence number int64+ * 56 flags uint64+ * 64 message id 16 bytes, least significant half first+ * 80 payload digest 32 bytes, SHA-256 of the payload+ * 112 payload type uint32+ * 116 payload length uint32+ * 120 payload+ * </pre>+ *+ * <p>The message id's halves are swapped relative to a textual UUID because the agent writes the+ * low 64 bits before the high ones; a client that reassembles the id the same way sees the UUID it+ * expects.+ */+public record AgentMessage(+ String messageType,+ int schemaVersion,+ long createdDate,+ long sequenceNumber,+ long flags,+ UUID messageId,+ int payloadType,+ byte[] payload) {++ public static final String OUTPUT_STREAM_DATA = "output_stream_data";+ public static final String INPUT_STREAM_DATA = "input_stream_data";+ public static final String ACKNOWLEDGE = "acknowledge";+ public static final String CHANNEL_CLOSED = "channel_closed";++ public static final int PAYLOAD_OUTPUT = 1;+ public static final int PAYLOAD_ERROR = 2;+ public static final int PAYLOAD_SIZE = 3;+ public static final int PAYLOAD_HANDSHAKE_REQUEST = 5;+ public static final int PAYLOAD_HANDSHAKE_RESPONSE = 6;+ public static final int PAYLOAD_HANDSHAKE_COMPLETE = 7;++ /** The header length the agent writes, which stops before the payload length field. */+ public static final int HEADER_LENGTH = 116;+ private static final int MESSAGE_TYPE_LENGTH = 32;+ private static final int DIGEST_LENGTH = 32;+ private static final int PAYLOAD_OFFSET = 120;+ private static final int SCHEMA_VERSION = 1;++ /** A message the agent side sends: a fresh id, the current time, and the given sequence. */+ public static AgentMessage outbound(String messageType, long sequenceNumber, int payloadType,+ byte[] payload) {+ return new AgentMessage(messageType, SCHEMA_VERSION, System.currentTimeMillis(),+ sequenceNumber, 0L, UUID.randomUUID(), payloadType, payload);+ }++ public byte[] encode() {+ byte[] body = payload != null ? payload : new byte[0];+ ByteBuffer buffer = ByteBuffer.allocate(PAYLOAD_OFFSET + body.length);+ buffer.putInt(HEADER_LENGTH);+ buffer.put(paddedMessageType());+ buffer.putInt(schemaVersion);+ buffer.putLong(createdDate);+ buffer.putLong(sequenceNumber);+ buffer.putLong(flags);+ buffer.putLong(messageId.getLeastSignificantBits());+ buffer.putLong(messageId.getMostSignificantBits());+ buffer.put(sha256(body));+ buffer.putInt(payloadType);+ buffer.putInt(body.length);+ buffer.put(body);+ return buffer.array();+ }++ public static AgentMessage decode(byte[] frame) {+ if (frame == null || frame.length < PAYLOAD_OFFSET) {+ throw new IllegalArgumentException("An agent message is at least " + PAYLOAD_OFFSET+ + " bytes, got " + (frame == null ? 0 : frame.length));+ }+ ByteBuffer buffer = ByteBuffer.wrap(frame);+ buffer.getInt();+ byte[] typeBytes = new byte[MESSAGE_TYPE_LENGTH];+ buffer.get(typeBytes);+ String messageType = new String(typeBytes, StandardCharsets.UTF_8).trim();+ int schemaVersion = buffer.getInt();+ long createdDate = buffer.getLong();+ long sequenceNumber = buffer.getLong();+ long flags = buffer.getLong();+ long leastSignificant = buffer.getLong();+ long mostSignificant = buffer.getLong();+ buffer.position(buffer.position() + DIGEST_LENGTH);+ int payloadType = buffer.getInt();+ int payloadLength = buffer.getInt();+ int available = Math.min(payloadLength, frame.length - PAYLOAD_OFFSET);+ byte[] payload = new byte[Math.max(available, 0)];+ if (payload.length > 0) {+ buffer.get(payload);+ }+ return new AgentMessage(messageType, schemaVersion, createdDate, sequenceNumber, flags,+ new UUID(mostSignificant, leastSignificant), payloadType, payload);+ }++ public String payloadAsString() {+ return payload == null ? "" : new String(payload, StandardCharsets.UTF_8);+ }++ private byte[] paddedMessageType() {+ byte[] padded = new byte[MESSAGE_TYPE_LENGTH];+ Arrays.fill(padded, (byte) ' ');+ byte[] raw = messageType.getBytes(StandardCharsets.UTF_8);+ System.arraycopy(raw, 0, padded, 0, Math.min(raw.length, MESSAGE_TYPE_LENGTH));+ return padded;+ }++ private static byte[] sha256(byte[] input) {+ try {+ return MessageDigest.getInstance("SHA-256").digest(input);+ } catch (NoSuchAlgorithmException e) {+ throw new IllegalStateException("SHA-256 is required to frame a Session Manager message", e);+ }+ }+}diff --git a/src/main/java/io/github/hectorvent/floci/services/ecs/exec/EcsExecChannelHandler.java b/src/main/java/io/github/hectorvent/floci/services/ecs/exec/EcsExecChannelHandler.javanew file mode 100644index 0000000000..3250578e91--- /dev/null+++ b/src/main/java/io/github/hectorvent/floci/services/ecs/exec/EcsExecChannelHandler.java@@ -0,0 +1,434 @@+package io.github.hectorvent.floci.services.ecs.exec;++import com.fasterxml.jackson.databind.JsonNode;+import com.fasterxml.jackson.databind.ObjectMapper;+import com.fasterxml.jackson.databind.node.ObjectNode;+import com.github.dockerjava.api.async.ResultCallback;+import com.github.dockerjava.api.model.Frame;+import io.github.hectorvent.floci.core.common.docker.ContainerLifecycleManager;+import io.vertx.core.Context;+import io.vertx.core.Vertx;+import io.vertx.core.buffer.Buffer;+import io.vertx.core.http.ServerWebSocket;+import io.vertx.ext.web.Router;+import io.vertx.ext.web.RoutingContext;+import jakarta.enterprise.context.ApplicationScoped;+import jakarta.enterprise.event.Observes;+import jakarta.inject.Inject;+import org.jboss.logging.Logger;++import java.io.Closeable;+import java.io.IOException;+import java.io.PipedInputStream;+import java.io.PipedOutputStream;+import java.nio.charset.StandardCharsets;+import java.util.Optional;+import java.util.concurrent.atomic.AtomicBoolean;+import java.util.concurrent.atomic.AtomicLong;++/**+ * The data channel behind {@code aws ecs execute-command}.+ *+ * <p>{@code ExecuteCommand} hands the caller a {@code streamUrl} pointing here; the AWS CLI passes+ * it to {@code session-manager-plugin}, which opens this WebSocket and speaks the Session Manager+ * protocol: a JSON handshake to claim the channel, then {@link AgentMessage} frames carrying the+ * terminal in both directions. Floci plays the agent half and bridges those frames to a+ * {@code docker exec} in the task's container.+ *+ * <p>The channel is claimed once. The token in the opening frame is the one+ * {@code ExecuteCommand} minted, and claiming it removes the session, so a captured stream URL+ * cannot be replayed into a second shell.+ *+ * <p>Two threads meet here. Every call into the Docker daemon blocks, so it runs on a worker+ * rather than on the event loop, and the daemon streams the container's output back on its own+ * thread. Frames are therefore written from the channel's Vert.x context only, which also keeps+ * the outbound sequence numbers in the order they go out on the wire.+ */+@ApplicationScoped+public class EcsExecChannelHandler {++ private static final Logger LOG = Logger.getLogger(EcsExecChannelHandler.class);++ /** Where the stream URL points. The path mirrors Session Manager's own data-channel path. */+ public static final String CHANNEL_PATH_PREFIX = "/v1/data-channel/";+ private static final String AGENT_VERSION = "3.3.0.0";++ private final EcsExecSessionRegistry sessions;+ private final ContainerLifecycleManager lifecycleManager;+ private final ObjectMapper objectMapper;+ private final Vertx vertx;++ @Inject+ public EcsExecChannelHandler(EcsExecSessionRegistry sessions,+ ContainerLifecycleManager lifecycleManager,+ ObjectMapper objectMapper,+ Vertx vertx) {+ this.sessions = sessions;+ this.lifecycleManager = lifecycleManager;+ this.objectMapper = objectMapper;+ this.vertx = vertx;+ }++ void init(@Observes Router router) {+ router.route(CHANNEL_PATH_PREFIX + ":sessionId").handler(this::upgrade);+ LOG.debugv("Registered the ECS Exec data channel on {0}*", CHANNEL_PATH_PREFIX);+ }++ private void upgrade(RoutingContext ctx) {+ String upgrade = ctx.request().getHeader("Upgrade");+ if (upgrade == null || !"websocket".equalsIgnoreCase(upgrade)) {+ ctx.next();+ return;+ }+ String sessionId = ctx.pathParam("sessionId");+ if (sessions.find(sessionId).isEmpty()) {+ ctx.response().setStatusCode(404).end();+ return;+ }+ ctx.request().toWebSocket()+ .onSuccess(webSocket -> new Channel(sessionId, webSocket).start())+ .onFailure(cause -> LOG.warnv("ECS Exec channel upgrade failed for session {0}: {1}",+ sessionId, cause.getMessage()));+ }++ /** One client's channel: the WebSocket, the exec it drives, and the sequencing between them. */+ private final class Channel {++ private final String sessionId;+ private final ServerWebSocket webSocket;+ private final Context context;+ private final AtomicLong outboundSequence = new AtomicLong();+ private final AtomicBoolean streaming = new AtomicBoolean();++ private volatile ExecSession session;+ private volatile String execId;+ private volatile PipedOutputStream containerInput;+ private volatile Closeables exec;++ Channel(String sessionId, ServerWebSocket webSocket) {+ this.sessionId = sessionId;+ this.webSocket = webSocket;+ this.context = vertx.getOrCreateContext();+ }++ void start() {+ webSocket.textMessageHandler(this::onOpenChannel);+ webSocket.binaryMessageHandler(this::onBinaryFrame);+ webSocket.closeHandler(_ -> shutdown());+ webSocket.exceptionHandler(cause -> {+ LOG.debugv("ECS Exec channel {0} failed: {1}", sessionId, cause.getMessage());+ shutdown();+ });+ }++ /**+ * The plugin's opening frame, which carries the token. Until it arrives and matches, the+ * channel does nothing: no exec is created and no output flows.+ */+ private void onOpenChannel(String message) {+ if (session != null) {+ return;+ }+ String token;+ try {+ JsonNode node = objectMapper.readTree(message);+ token = node.path("TokenValue").asText(null);+ } catch (Exception e) {+ LOG.debugv("ECS Exec channel {0} sent an unreadable opening frame: {1}",+ sessionId, e.getMessage());+ webSocket.close((short) 1002, "Malformed opening message");+ return;+ }+ Optional<ExecSession> claimed = sessions.claim(sessionId, token);+ if (claimed.isEmpty()) {+ webSocket.close((short) 1008, "Invalid session token");+ return;+ }+ session = claimed.get();+ createExec();+ }++ /**+ * Creates the exec and offers the handshake. The command is not started yet: the agent+ * offers the session type first and only runs anything once the client has accepted it,+ * so the client cannot be handed output for a channel it has not finished opening.+ */+ private void createExec() {+ ExecSession current = session;+ vertx.<String>executeBlocking(() -> lifecycleManager.getDockerClient()+ .execCreateCmd(current.runtimeId())+ .withCmd(current.command().toArray(new String[0]))+ .withAttachStdin(true)+ .withAttachStdout(true)+ .withAttachStderr(true)+ .withTty(current.interactive())+ .exec()+ .getId(), false)+ .onSuccess(id -> {+ execId = id;+ sendHandshakeRequest();+ })+ .onFailure(cause -> failChannel(cause, current.containerName()));+ }++ /** Attaches to the exec, which starts the command and begins streaming its output back. */+ private void startStreaming() {+ if (!streaming.compareAndSet(false, true)) {+ return;+ }+ ExecSession current = session;+ String id = execId;+ // The pipe is wired up before the attach is dispatched, so input the client sends the+ // moment the handshake completes has somewhere to go rather than being dropped.+ PipedOutputStream toContainer = new PipedOutputStream();+ PipedInputStream execStdin;+ try {+ execStdin = new PipedInputStream(toContainer);+ } catch (IOException e) {+ failChannel(e, current.containerName());+ return;+ }+ containerInput = toContainer;+ vertx.<Closeables>executeBlocking(() -> new Closeables(lifecycleManager.getDockerClient()+ .execStartCmd(id)+ .withStdIn(execStdin)+ .withTty(current.interactive())+ .exec(new ExecFrameCallback(this)), execStdin), false)+ .onSuccess(started -> exec = started)+ .onFailure(cause -> failChannel(cause, current.containerName()));+ }++ private void failChannel(Throwable cause, String containerName) {+ LOG.warnv("ECS Exec session {0} could not start in container {1}: {2}",+ sessionId, containerName, cause.getMessage());+ sendError("Failed to start the command in container " + containerName+ + ": " + cause.getMessage());+ onContext(() -> webSocket.close((short) 1011, "Exec failed to start"));+ }++ private void onBinaryFrame(Buffer buffer) {+ if (session == null) {+ return;+ }+ AgentMessage message;+ try {+ message = AgentMessage.decode(buffer.getBytes());+ } catch (IllegalArgumentException e) {+ LOG.debugv("ECS Exec channel {0} sent an undecodable frame: {1}", sessionId, e.getMessage());+ return;+ }+ switch (message.messageType()) {+ case AgentMessage.INPUT_STREAM_DATA -> {+ acknowledge(message);+ handleInput(message);+ }+ case AgentMessage.CHANNEL_CLOSED -> shutdown();+ case AgentMessage.ACKNOWLEDGE -> { /* the client confirming our output; nothing to do */ }+ default -> LOG.debugv("Ignoring ECS Exec message of type {0}", message.messageType());+ }+ }++ private void handleInput(AgentMessage message) {+ switch (message.payloadType()) {+ case AgentMessage.PAYLOAD_HANDSHAKE_RESPONSE -> {+ sendHandshakeComplete();+ startStreaming();+ }+ case AgentMessage.PAYLOAD_SIZE -> resizeTerminal(message.payloadAsString());+ case AgentMessage.PAYLOAD_OUTPUT -> writeToContainer(message.payload());+ default -> LOG.debugv("Ignoring ECS Exec payload of type {0}", message.payloadType());+ }+ }++ private void writeToContainer(byte[] payload) {+ PipedOutputStream stream = containerInput;+ if (stream == null || payload == null || payload.length == 0) {+ return;+ }+ try {+ stream.write(payload);+ stream.flush();+ } catch (IOException e) {+ LOG.debugv("ECS Exec session {0} could not write to the container: {1}",+ sessionId, e.getMessage());+ shutdown();+ }+ }++ private void resizeTerminal(String payload) {+ String id = execId;+ if (id == null) {+ return;+ }+ int rows;+ int cols;+ try {+ JsonNode size = objectMapper.readTree(payload);+ rows = size.path("rows").asInt(0);+ cols = size.path("cols").asInt(0);+ } catch (Exception e) {+ LOG.debugv("ECS Exec session {0} sent an unreadable terminal size: {1}",+ sessionId, e.getMessage());+ return;+ }+ if (rows <= 0 || cols <= 0) {+ return;+ }+ vertx.executeBlocking(() -> lifecycleManager.getDockerClient().resizeExecCmd(id)+ .withSize(rows, cols).exec(), false)+ .onFailure(cause -> LOG.debugv("ECS Exec session {0} could not resize the terminal: {1}",+ sessionId, cause.getMessage()));+ }++ private void sendHandshakeRequest() {+ ObjectNode action = objectMapper.createObjectNode();+ action.put("ActionType", "SessionType");+ ObjectNode parameters = action.putObject("ActionParameters");+ parameters.put("SessionType", "Standard_Stream");+ parameters.putNull("Properties");++ ObjectNode payload = objectMapper.createObjectNode();+ payload.put("AgentVersion", AGENT_VERSION);+ payload.putArray("RequestedClientActions").add(action);++ send(AgentMessage.PAYLOAD_HANDSHAKE_REQUEST, asBytes(payload));+ }++ private void sendHandshakeComplete() {+ ObjectNode payload = objectMapper.createObjectNode();+ payload.put("HandshakeTimeToComplete", 0);+ payload.put("CustomerMessage", "");+ send(AgentMessage.PAYLOAD_HANDSHAKE_COMPLETE, asBytes(payload));+ }++ private void sendError(String message) {+ send(AgentMessage.PAYLOAD_ERROR, message.getBytes(StandardCharsets.UTF_8));+ }++ void sendOutput(byte[] payload) {+ send(AgentMessage.PAYLOAD_OUTPUT, payload);+ }++ /**+ * The sequence number is taken on the context, immediately before the frame is written, so+ * that the numbers the client sees arrive in order however many threads produced them.+ */+ private void send(int payloadType, byte[] payload) {+ onContext(() -> writeFrame(AgentMessage.outbound(AgentMessage.OUTPUT_STREAM_DATA,+ outboundSequence.getAndIncrement(), payloadType, payload)));+ }++ private void acknowledge(AgentMessage message) {+ ObjectNode payload = objectMapper.createObjectNode();+ payload.put("AcknowledgedMessageType", message.messageType());+ payload.put("AcknowledgedMessageId", message.messageId().toString());+ payload.put("AcknowledgedMessageSequenceNumber", message.sequenceNumber());+ payload.put("IsSequentialMessage", true);+ onContext(() -> writeFrame(AgentMessage.outbound(AgentMessage.ACKNOWLEDGE,+ message.sequenceNumber(), AgentMessage.PAYLOAD_OUTPUT, asBytes(payload))));+ }++ private void writeFrame(AgentMessage message) {+ if (webSocket.isClosed()) {+ return;+ }+ try {+ webSocket.writeBinaryMessage(Buffer.buffer(message.encode()));+ } catch (RuntimeException e) {+ LOG.debugv("ECS Exec session {0} could not write a frame: {1}", sessionId, e.getMessage());+ }+ }++ /**+ * Runs on the channel's context. Everything that touches the WebSocket goes through here,+ * including calls already on that context, so the frames keep their submission order.+ */+ private void onContext(Runnable action) {+ context.runOnContext(ignored -> action.run());+ }++ void closeAfterExec() {+ onContext(() -> {+ if (!webSocket.isClosed()) {+ writeFrame(AgentMessage.outbound(AgentMessage.CHANNEL_CLOSED,+ outboundSequence.getAndIncrement(), AgentMessage.PAYLOAD_OUTPUT, new byte[0]));+ webSocket.close();+ }+ });+ shutdown();+ }++ /** Closing the exec streams talks to the daemon, so it too stays off the event loop. */+ private void shutdown() {+ Closeables open = exec;+ PipedOutputStream stream = containerInput;+ exec = null;+ containerInput = null;+ if (open == null && stream == null) {+ return;+ }+ vertx.executeBlocking(() -> {+ if (open != null) {+ open.close();+ }+ if (stream != null) {+ Closeables.closeQuietly(stream);+ }+ return null;+ }, false);+ }++ private byte[] asBytes(ObjectNode node) {+ try {+ return objectMapper.writeValueAsBytes(node);+ } catch (Exception e) {+ throw new IllegalStateException("Could not serialize an ECS Exec payload", e);+ }+ }+ }++ /** The exec's output callback and its stdin pipe, closed together when the channel ends. */+ private record Closeables(Closeable callback, Closeable stdin) {+ void close() {+ closeQuietly(callback);+ closeQuietly(stdin);+ }++ private static void closeQuietly(Closeable closeable) {+ try {+ closeable.close();+ } catch (IOException | RuntimeException e) {+ LOG.debugv("Could not close an ECS Exec stream: {0}", e.getMessage());+ }+ }+ }++ /** Streams the container's output back over the channel, one frame at a time. */+ private static final class ExecFrameCallback extends ResultCallback.Adapter<Frame> {++ private final Channel channel;++ private ExecFrameCallback(Channel channel) {+ this.channel = channel;+ }++ @Override+ public void onNext(Frame frame) {+ byte[] payload = frame.getPayload();+ if (payload != null && payload.length > 0) {+ channel.sendOutput(payload);+ }+ }++ @Override+ public void onComplete() {+ channel.closeAfterExec();+ }++ @Override+ public void onError(Throwable throwable) {+ LOG.debugv("ECS Exec output stream ended with an error: {0}", throwable.getMessage());+ channel.closeAfterExec();+ }+ }+}diff --git a/src/main/java/io/github/hectorvent/floci/services/ecs/exec/EcsExecSessionRegistry.java b/src/main/java/io/github/hectorvent/floci/services/ecs/exec/EcsExecSessionRegistry.javanew file mode 100644index 0000000000..245fdfc7b2--- /dev/null+++ b/src/main/java/io/github/hectorvent/floci/services/ecs/exec/EcsExecSessionRegistry.java@@ -0,0 +1,125 @@+package io.github.hectorvent.floci.services.ecs.exec;++import io.github.hectorvent.floci.core.common.Resettable;+import jakarta.enterprise.context.ApplicationScoped;+import jakarta.inject.Inject;+import org.jboss.logging.Logger;++import java.nio.charset.StandardCharsets;+import java.security.MessageDigest;+import java.security.SecureRandom;+import java.time.Clock;+import java.time.Duration;+import java.time.Instant;+import java.util.Base64;+import java.util.List;+import java.util.Map;+import java.util.Optional;+import java.util.UUID;+import java.util.concurrent.ConcurrentHashMap;++/**+ * The open {@code ExecuteCommand} sessions, keyed by session id.+ *+ * <p>A session is created by the ECS API and claimed once, by the client that opens the data+ * channel with the matching token. Sessions are in memory and short lived, the way AWS's are: the+ * token is single use and expires if nobody connects.+ */+@ApplicationScoped+public class EcsExecSessionRegistry implements Resettable {++ private static final Logger LOG = Logger.getLogger(EcsExecSessionRegistry.class);++ /** How long a session waits for its client before it is dropped. */+ static final Duration SESSION_TTL = Duration.ofMinutes(5);++ private static final SecureRandom RANDOM = new SecureRandom();++ private final Map<String, ExecSession> sessions = new ConcurrentHashMap<>();++ private final Clock clock;++ @Inject+ public EcsExecSessionRegistry(Clock clock) {+ this.clock = clock;+ }++ /** With the system clock, for callers that assemble the registry without CDI. */+ public EcsExecSessionRegistry() {+ this(Clock.systemUTC());+ }++ /** Mints a session for a container, returning it with the token the client must present. */+ public ExecSession create(String taskArn, String clusterArn, String containerName,+ String containerArn, String runtimeId, List<String> command,+ boolean interactive) {+ expireStaleSessions();+ String sessionId = "ecs-execute-command-" + UUID.randomUUID().toString().replace("-", "");+ byte[] token = new byte[32];+ RANDOM.nextBytes(token);+ ExecSession session = new ExecSession(sessionId,+ Base64.getUrlEncoder().withoutPadding().encodeToString(token),+ taskArn, clusterArn, containerName, containerArn, runtimeId, command, interactive,+ clock.instant());+ sessions.put(sessionId, session);+ return session;+ }++ /**+ * Claims a session for a connecting client. The session is removed, so a replayed token cannot+ * open a second channel into the container. The token is the only gate in front of an+ * interactive shell, so it is compared in constant time, and only for a session that is still+ * within its TTL.+ */+ public Optional<ExecSession> claim(String sessionId, String tokenValue) {+ ExecSession session = liveSession(sessionId);+ if (session == null) {+ return Optional.empty();+ }+ if (tokenValue == null || !MessageDigest.isEqual(+ session.tokenValue().getBytes(StandardCharsets.UTF_8),+ tokenValue.getBytes(StandardCharsets.UTF_8))) {+ LOG.warnv("Rejected an ECS Exec channel for session {0}: the token does not match", sessionId);+ return Optional.empty();+ }+ return sessions.remove(sessionId, session) ? Optional.of(session) : Optional.empty();+ }++ /** The session behind a data channel, or empty once it has expired or been claimed. */+ public Optional<ExecSession> find(String sessionId) {+ return Optional.ofNullable(liveSession(sessionId));+ }++ /**+ * The session under {@code sessionId}, or null if there is none or it has outlived+ * {@link #SESSION_TTL}. An expired session is dropped here rather than waiting for the next+ * {@code create()}: nothing else sweeps the map, so a session nobody connects to would+ * otherwise stay claimable, token and all, for as long as the emulator runs.+ */+ private ExecSession liveSession(String sessionId) {+ ExecSession session = sessions.get(sessionId);+ if (session == null) {+ return null;+ }+ if (session.createdAt().isBefore(cutoff())) {+ sessions.remove(sessionId, session);+ LOG.debugv("Dropped the expired ECS Exec session {0}", sessionId);+ return null;+ }+ return session;+ }++ private void expireStaleSessions() {+ Instant cutoff = cutoff();+ sessions.values().removeIf(session -> session.createdAt().isBefore(cutoff));+ }++ private Instant cutoff() {+ return clock.instant().minus(SESSION_TTL);+ }++ @Override+ public void clear() {+ sessions.clear();+ }+}diff --git a/src/main/java/io/github/hectorvent/floci/services/ecs/exec/ExecSession.java b/src/main/java/io/github/hectorvent/floci/services/ecs/exec/ExecSession.javanew file mode 100644index 0000000000..a62c3b7aec--- /dev/null+++ b/src/main/java/io/github/hectorvent/floci/services/ecs/exec/ExecSession.java@@ -0,0 +1,24 @@+package io.github.hectorvent.floci.services.ecs.exec;++import io.quarkus.runtime.annotations.RegisterForReflection;++import java.time.Instant;+import java.util.List;++/**+ * One {@code ExecuteCommand} session: what to run, in which container, and the token the client+ * has to present when it opens the data channel.+ */+@RegisterForReflection+public record ExecSession(+ String sessionId,+ String tokenValue,+ String taskArn,+ String clusterArn,+ String containerName,+ String containerArn,+ String runtimeId,+ List<String> command,+ boolean interactive,+ Instant createdAt) {+}diff --git a/src/main/resources/application.yml b/src/main/resources/application.ymlindex 8aa679e287..02634c83fd 100644--- a/src/main/resources/application.yml+++ b/src/main/resources/application.yml@@ -108,6 +108,7 @@ quarkus:- --initialize-at-run-time=io.github.hectorvent.floci.services.lambda.launcher.LambdaExecutionRoleCredentials- --initialize-at-run-time=io.github.hectorvent.floci.services.ssoportal.SsoPortalService- --initialize-at-run-time=io.github.hectorvent.floci.services.redshift.proxy.S3CopySimulator+ - --initialize-at-run-time=io.github.hectorvent.floci.services.ecs.exec.EcsExecSessionRegistry# snappy-java (Firehose Snappy/HADOOP_SNAPPY delivery) extracts and loads a# bundled JNI library from the static initializers of these two classes.- --initialize-at-run-time=org.xerial.snappy.Snappydiff --git a/src/test/java/io/github/hectorvent/floci/services/ecs/EcsExecuteCommandIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/services/ecs/EcsExecuteCommandIntegrationTest.javanew file mode 100644index 0000000000..7c4bcc4df5--- /dev/null+++ b/src/test/java/io/github/hectorvent/floci/services/ecs/EcsExecuteCommandIntegrationTest.java@@ -0,0 +1,153 @@+package io.github.hectorvent.floci.services.ecs;++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.hamcrest.Matchers.containsString;+import static org.hamcrest.Matchers.equalTo;+import static org.hamcrest.Matchers.hasSize;++/**+ * {@code ExecuteCommand}'s control-plane half: what a task has to be for a session to be opened at+ * all, and what the caller gets back when it is.+ *+ * <p>Tests run with ECS in mock mode, so the tasks here have container models but nothing running+ * behind them: the session gate is exercised up to the point where a real container would be+ * needed. {@code EcsExecChannelDockerIntegrationTest} covers the rest against Docker.+ */+@QuarkusTest+class EcsExecuteCommandIntegrationTest {++ private static final String TARGET = "AmazonEC2ContainerServiceV20141113.";+ private static final String CT = "application/x-amz-json-1.1";+ private static final String CLUSTER = "exec-cluster";+ private static final String NETWORK =+ "\"networkConfiguration\":{\"awsvpcConfiguration\":{\"subnets\":"+ + "[\"subnet-default-us-east-1-a\"]}}";++ @BeforeAll+ static void configure() {+ RestAssuredJsonUtils.configureAwsContentTypes();+ }++ private static Response call(String action, String body, int expectedStatus) {+ return given().contentType(CT).header("X-Amz-Target", TARGET + action)+ .body(body)+ .when().post("/")+ .then().statusCode(expectedStatus)+ .extract().response();+ }++ private static String runTask(String family, boolean enableExecuteCommand) {+ call("CreateCluster", "{\"clusterName\":\"" + CLUSTER + "\"}", 200);+ call("RegisterTaskDefinition", "{\"family\":\"" + family + "\","+ + "\"requiresCompatibilities\":[\"FARGATE\"],\"networkMode\":\"awsvpc\","+ + "\"cpu\":\"256\",\"memory\":\"512\",\"containerDefinitions\":"+ + "[{\"name\":\"app\",\"image\":\"nginx:latest\"}]}", 200);+ return call("RunTask", "{\"cluster\":\"" + CLUSTER + "\",\"taskDefinition\":\"" + family+ + "\",\"launchType\":\"FARGATE\"," + NETWORK + ",\"enableExecuteCommand\":"+ + enableExecuteCommand + "}", 200)+ .jsonPath().getString("tasks[0].taskArn");+ }++ @Test+ void aTaskRunWithExecuteCommandEnabledReportsTheAgent() {+ String taskArn = runTask("exec-enabled", true);++ call("DescribeTasks", "{\"cluster\":\"" + CLUSTER + "\",\"tasks\":[\"" + taskArn + "\"]}", 200)+ .then()+ .body("tasks[0].enableExecuteCommand", equalTo(true))+ .body("tasks[0].containers", hasSize(1))+ .body("tasks[0].containers[0].managedAgents[0].name", equalTo("ExecuteCommandAgent"))+ .body("tasks[0].containers[0].managedAgents[0].lastStatus", equalTo("RUNNING"));+ }++ @Test+ void executeCommandIsRefusedWhenTheTaskWasNotRunWithItEnabled() {+ String taskArn = runTask("exec-disabled", false);++ call("ExecuteCommand", "{\"cluster\":\"" + CLUSTER + "\",\"task\":\"" + taskArn+ + "\",\"container\":\"app\",\"command\":\"/bin/sh\",\"interactive\":true}", 400)+ .then()+ .body("__type", containsString("InvalidParameterException"))+ .body("message", containsString("execute command was not enabled"));+ }++ @Test+ void executeCommandIsRefusedForAContainerThatIsNotInTheTask() {+ String taskArn = runTask("exec-wrong-container", true);++ call("ExecuteCommand", "{\"cluster\":\"" + CLUSTER + "\",\"task\":\"" + taskArn+ + "\",\"container\":\"sidecar\",\"command\":\"/bin/sh\",\"interactive\":true}", 400)+ .then().body("message", containsString("sidecar"));+ }++ @Test+ void executeCommandIsRefusedWhenNothingIsRunningBehindTheContainer() {+ // Mock mode reports the container but has no runtime behind it, which is exactly the+ // state AWS reports as a disconnected target rather than a missing one.+ String taskArn = runTask("exec-no-runtime", true);++ call("ExecuteCommand", "{\"cluster\":\"" + CLUSTER + "\",\"task\":\"" + taskArn+ + "\",\"container\":\"app\",\"command\":\"/bin/sh\",\"interactive\":true}", 400)+ .then()+ .body("__type", containsString("TargetNotConnectedException"));+ }++ @Test+ void executeCommandIsRefusedOnAStoppedTask() {+ String taskArn = runTask("exec-stopped", true);+ call("StopTask", "{\"cluster\":\"" + CLUSTER + "\",\"task\":\"" + taskArn + "\"}", 200);++ call("ExecuteCommand", "{\"cluster\":\"" + CLUSTER + "\",\"task\":\"" + taskArn+ + "\",\"container\":\"app\",\"command\":\"/bin/sh\",\"interactive\":true}", 400)+ .then()+ .body("__type", containsString("TargetNotConnectedException"))+ .body("message", containsString("not running"));+ }++ @Test+ void executeCommandIsRefusedWhenItIsNotInteractive() {+ String taskArn = runTask("exec-non-interactive", true);++ call("ExecuteCommand", "{\"cluster\":\"" + CLUSTER + "\",\"task\":\"" + taskArn+ + "\",\"container\":\"app\",\"command\":\"/bin/sh\",\"interactive\":false}", 400)+ .then()+ .body("__type", containsString("InvalidParameterException"))+ .body("message", containsString("interactive"));+ }++ @Test+ void executeCommandIsRefusedForAClusterThatDoesNotExist() {+ String taskArn = runTask("exec-unknown-cluster", true);++ call("ExecuteCommand", "{\"cluster\":\"no-such-cluster\",\"task\":\"" + taskArn+ + "\",\"container\":\"app\",\"command\":\"/bin/sh\",\"interactive\":true}", 400)+ .then().body("__type", containsString("ClusterNotFoundException"));+ }++ @Test+ void executeCommandIsRefusedForATaskInAnotherCluster() {+ String taskArn = runTask("exec-other-cluster", true);+ call("CreateCluster", "{\"clusterName\":\"exec-bystander\"}", 200);++ call("ExecuteCommand", "{\"cluster\":\"exec-bystander\",\"task\":\"" + taskArn+ + "\",\"container\":\"app\",\"command\":\"/bin/sh\",\"interactive\":true}", 400)+ .then()+ .body("__type", containsString("InvalidParameterException"))+ .body("message", containsString("is not part of the cluster"));+ }++ @Test+ void executeCommandRejectsAnEmptyCommand() {+ String taskArn = runTask("exec-empty-command", true);++ call("ExecuteCommand", "{\"cluster\":\"" + CLUSTER + "\",\"task\":\"" + taskArn+ + "\",\"container\":\"app\",\"command\":\"\",\"interactive\":true}", 400)+ .then().body("message", containsString("command cannot be empty"));+ }+}diff --git a/src/test/java/io/github/hectorvent/floci/services/ecs/EcsFargateEdgeCaseIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/services/ecs/EcsFargateEdgeCaseIntegrationTest.javaindex 227d93d5aa..ae412d1d69 100644--- a/src/test/java/io/github/hectorvent/floci/services/ecs/EcsFargateEdgeCaseIntegrationTest.java+++ b/src/test/java/io/github/hectorvent/floci/services/ecs/EcsFargateEdgeCaseIntegrationTest.java@@ -1206,6 +1206,19 @@ class EcsFargateEdgeCaseIntegrationTest {.then().body("message", containsString("containerInstances"));}+ @Test+ void executeCommandOnlySupportsInteractiveSessions() {+ String family = seed("edge-interactive");+ String taskArn = call("RunTask", "{\"cluster\":\"" + CLUSTER + "\",\"taskDefinition\":\""+ + family + "\",\"launchType\":\"FARGATE\"," + NETWORK+ + ",\"enableExecuteCommand\":true}", 200)+ .jsonPath().getString("tasks[0].taskArn");++ call("ExecuteCommand", "{\"cluster\":\"" + CLUSTER + "\",\"task\":\"" + taskArn+ + "\",\"container\":\"app\",\"command\":\"/bin/sh\",\"interactive\":false}", 400)+ .then().body("message", containsString("interactive"));+ }+// ── The Service shape's own members ──────────────────────────────────────@Testdiff --git a/src/test/java/io/github/hectorvent/floci/services/ecs/exec/AgentMessageTest.java b/src/test/java/io/github/hectorvent/floci/services/ecs/exec/AgentMessageTest.javanew file mode 100644index 0000000000..f06de505d2--- /dev/null+++ b/src/test/java/io/github/hectorvent/floci/services/ecs/exec/AgentMessageTest.java@@ -0,0 +1,89 @@+package io.github.hectorvent.floci.services.ecs.exec;++import org.junit.jupiter.api.Test;++import java.nio.ByteBuffer;+import java.nio.charset.StandardCharsets;+import java.security.MessageDigest;+import java.util.UUID;++import static org.junit.jupiter.api.Assertions.assertArrayEquals;+import static org.junit.jupiter.api.Assertions.assertEquals;+import static org.junit.jupiter.api.Assertions.assertThrows;++/**+ * The Session Manager frame layout. {@code session-manager-plugin} parses these bytes by fixed+ * offset, so the field order, the padding, the digest and the swapped halves of the message id are+ * the contract: get one wrong and the plugin drops the channel without saying why.+ */+class AgentMessageTest {++ private static final int PAYLOAD_OFFSET = 120;++ @Test+ void encodeWritesTheHeaderTheAgentWrites() throws Exception {+ UUID messageId = UUID.fromString("2f1b6a4e-9c3d-4f7a-8b2e-1d0c9a8b7c6d");+ byte[] payload = "hello".getBytes(StandardCharsets.UTF_8);+ AgentMessage message = new AgentMessage(AgentMessage.OUTPUT_STREAM_DATA, 1, 1700000000000L,+ 7L, 0L, messageId, AgentMessage.PAYLOAD_OUTPUT, payload);++ byte[] encoded = message.encode();+ ByteBuffer buffer = ByteBuffer.wrap(encoded);++ assertEquals(AgentMessage.HEADER_LENGTH, buffer.getInt(), "the header length comes first");+ byte[] type = new byte[32];+ buffer.get(type);+ assertEquals(AgentMessage.OUTPUT_STREAM_DATA,+ new String(type, StandardCharsets.UTF_8).trim());+ assertEquals(' ', (char) type[type.length - 1], "the message type is padded with spaces");+ assertEquals(1, buffer.getInt(), "schema version");+ assertEquals(1700000000000L, buffer.getLong(), "created date");+ assertEquals(7L, buffer.getLong(), "sequence number");+ assertEquals(0L, buffer.getLong(), "flags");+ // The low half of the id is written before the high half.+ assertEquals(messageId.getLeastSignificantBits(), buffer.getLong());+ assertEquals(messageId.getMostSignificantBits(), buffer.getLong());+ byte[] digest = new byte[32];+ buffer.get(digest);+ assertArrayEquals(MessageDigest.getInstance("SHA-256").digest(payload), digest,+ "the digest covers the payload");+ assertEquals(AgentMessage.PAYLOAD_OUTPUT, buffer.getInt(), "payload type");+ assertEquals(payload.length, buffer.getInt(), "payload length");+ assertEquals(PAYLOAD_OFFSET + payload.length, encoded.length);+ }++ @Test+ void decodeReadsBackWhatEncodeWrote() {+ UUID messageId = UUID.randomUUID();+ byte[] payload = "{\"cols\":120,\"rows\":40}".getBytes(StandardCharsets.UTF_8);+ AgentMessage original = new AgentMessage(AgentMessage.INPUT_STREAM_DATA, 1, 42L, 3L, 1L,+ messageId, AgentMessage.PAYLOAD_SIZE, payload);++ AgentMessage decoded = AgentMessage.decode(original.encode());++ assertEquals(AgentMessage.INPUT_STREAM_DATA, decoded.messageType());+ assertEquals(1, decoded.schemaVersion());+ assertEquals(42L, decoded.createdDate());+ assertEquals(3L, decoded.sequenceNumber());+ assertEquals(1L, decoded.flags());+ assertEquals(messageId, decoded.messageId());+ assertEquals(AgentMessage.PAYLOAD_SIZE, decoded.payloadType());+ assertEquals("{\"cols\":120,\"rows\":40}", decoded.payloadAsString());+ }++ @Test+ void anEmptyPayloadRoundTrips() {+ AgentMessage decoded = AgentMessage.decode(+ AgentMessage.outbound(AgentMessage.CHANNEL_CLOSED, 0, AgentMessage.PAYLOAD_OUTPUT,+ new byte[0]).encode());++ assertEquals(AgentMessage.CHANNEL_CLOSED, decoded.messageType());+ assertEquals(0, decoded.payload().length);+ }++ @Test+ void aTruncatedFrameIsRejectedRatherThanMisread() {+ byte[] tooShort = new byte[64];+ assertThrows(IllegalArgumentException.class, () -> AgentMessage.decode(tooShort));+ }+}diff --git a/src/test/java/io/github/hectorvent/floci/services/ecs/exec/EcsExecChannelDockerIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/services/ecs/exec/EcsExecChannelDockerIntegrationTest.javanew file mode 100644index 0000000000..3e4a4f7c89--- /dev/null+++ b/src/test/java/io/github/hectorvent/floci/services/ecs/exec/EcsExecChannelDockerIntegrationTest.java@@ -0,0 +1,210 @@+package io.github.hectorvent.floci.services.ecs.exec;++import com.github.dockerjava.api.DockerClient;+import io.github.hectorvent.floci.services.ecs.container.EcsContainerManager;+import io.github.hectorvent.floci.services.ecs.container.EcsTaskHandle;+import io.github.hectorvent.floci.services.ecs.model.ContainerDefinition;+import io.github.hectorvent.floci.services.ecs.model.EcsTask;+import io.github.hectorvent.floci.services.ecs.model.TaskDefinition;+import io.quarkus.test.junit.QuarkusTest;+import io.restassured.RestAssured;+import io.vertx.core.Vertx;+import io.vertx.core.buffer.Buffer;+import io.vertx.core.http.HttpClient;+import io.vertx.core.http.WebSocket;+import jakarta.inject.Inject;+import org.junit.jupiter.api.Assumptions;+import org.junit.jupiter.api.BeforeEach;+import org.junit.jupiter.api.Test;++import java.nio.charset.StandardCharsets;+import java.util.List;+import java.util.UUID;+import java.util.concurrent.BlockingQueue;+import java.util.concurrent.LinkedBlockingQueue;+import java.util.concurrent.TimeUnit;++import static org.junit.jupiter.api.Assertions.assertEquals;+import static org.junit.jupiter.api.Assertions.assertNotNull;+import static org.junit.jupiter.api.Assertions.assertTrue;++/**+ * ECS Exec end to end, against a real container.+ *+ * <p>This drives the client half of the Session Manager protocol the way+ * {@code session-manager-plugin} does: open the channel with the session token, answer the+ * handshake, then read the command's output off the stream. The plugin binary is not available in+ * CI, so the protocol is exercised from here rather than from it.+ */+@QuarkusTest+class EcsExecChannelDockerIntegrationTest {++ private static final String BUSYBOX_IMAGE = "public.ecr.aws/docker/library/busybox:latest";+ private static final String TASK_ARN =+ "arn:aws:ecs:us-east-1:000000000000:task/exec-cluster/execdockertask";++ @Inject+ EcsContainerManager containerManager;++ @Inject+ EcsExecSessionRegistry sessions;++ @Inject+ DockerClient dockerClient;++ @Inject+ Vertx vertx;++ @BeforeEach+ void requireDocker() {+ Assumptions.assumeTrue(isDockerAvailable(),+ "Docker daemon must be available for the ECS Exec channel test");+ }++ @Test+ void aClientDrivingTheProtocolGetsTheCommandsOutput() throws Exception {+ String suffix = UUID.randomUUID().toString().substring(0, 8);+ ContainerDefinition app = new ContainerDefinition();+ app.setName("app");+ app.setImage(BUSYBOX_IMAGE);+ app.setCommand(List.of("sleep", "120"));++ TaskDefinition taskDefinition = new TaskDefinition();+ taskDefinition.setFamily("exec-docker-" + suffix);+ taskDefinition.setContainerDefinitions(List.of(app));++ EcsTask task = new EcsTask();+ task.setTaskArn(TASK_ARN + suffix);+ task.setEnableExecuteCommand(true);++ EcsTaskHandle handle = containerManager.startTask(task, taskDefinition, List.of(), "us-east-1");+ try {+ // The agent is reported as running, which is what a client checks before connecting.+ assertEquals(ManagedAgentStatus.RUNNING, ManagedAgentStatus.of(task));++ String runtimeId = handle.getContainerIds().get("app");+ ExecSession session = sessions.create(task.getTaskArn(),+ "arn:aws:ecs:us-east-1:000000000000:cluster/exec-cluster", "app",+ "arn:aws:ecs:us-east-1:000000000000:container/exec/app", runtimeId,+ List.of("/bin/sh", "-c", "echo exec-channel-ok"), false);++ PluginClient client = new PluginClient(vertx, session);+ try {+ client.open();++ AgentMessage handshakeRequest = client.next();+ assertEquals(AgentMessage.OUTPUT_STREAM_DATA, handshakeRequest.messageType());+ assertEquals(AgentMessage.PAYLOAD_HANDSHAKE_REQUEST, handshakeRequest.payloadType());+ assertTrue(handshakeRequest.payloadAsString().contains("Standard_Stream"),+ "the agent asks for a standard stream session: "+ + handshakeRequest.payloadAsString());++ client.sendHandshakeResponse();++ String output = client.readUntil("exec-channel-ok");+ assertTrue(output.contains("exec-channel-ok"),+ "the command's output must reach the channel, got: " + output);+ } finally {+ client.close();+ }++ // The session was single use: the token cannot open a second shell.+ assertTrue(sessions.find(session.sessionId()).isEmpty(),+ "a claimed session must not be claimable again");+ } finally {+ containerManager.stopTask(handle);+ }+ }++ /** Reads the ExecuteCommandAgent status a task's containers report. */+ private enum ManagedAgentStatus {+ RUNNING, ABSENT;++ static ManagedAgentStatus of(EcsTask task) {+ return task.getContainers() != null+ && task.getContainers().stream().anyMatch(container ->+ container.getManagedAgents() != null+ && container.getManagedAgents().stream().anyMatch(agent ->+ "ExecuteCommandAgent".equals(agent.name())+ && "RUNNING".equals(agent.lastStatus())))+ ? RUNNING : ABSENT;+ }+ }++ /** The half of the Session Manager protocol that {@code session-manager-plugin} implements. */+ private static final class PluginClient {++ private final Vertx vertx;+ private final ExecSession session;+ private final BlockingQueue<AgentMessage> received = new LinkedBlockingQueue<>();++ private HttpClient httpClient;+ private WebSocket webSocket;+ private long sequence;++ PluginClient(Vertx vertx, ExecSession session) {+ this.vertx = vertx;+ this.session = session;+ }++ void open() throws Exception {+ httpClient = vertx.createHttpClient();+ webSocket = httpClient.webSocket(RestAssured.port, "localhost",+ EcsExecChannelHandler.CHANNEL_PATH_PREFIX + session.sessionId())+ .toCompletionStage().toCompletableFuture().get(20, TimeUnit.SECONDS);+ webSocket.binaryMessageHandler(buffer -> received.add(AgentMessage.decode(buffer.getBytes())));+ webSocket.writeTextMessage("{\"MessageSchemaVersion\":\"1.0\",\"RequestId\":\""+ + UUID.randomUUID() + "\",\"TokenValue\":\"" + session.tokenValue()+ + "\",\"ClientId\":\"" + UUID.randomUUID() + "\"}");+ }++ void sendHandshakeResponse() {+ String payload = "{\"ClientVersion\":\"1.2.0.0\",\"ProcessedClientActions\":"+ + "[{\"ActionType\":\"SessionType\",\"ActionStatus\":1}],\"Errors\":\"\"}";+ AgentMessage response = AgentMessage.outbound(AgentMessage.INPUT_STREAM_DATA, sequence++,+ AgentMessage.PAYLOAD_HANDSHAKE_RESPONSE, payload.getBytes(StandardCharsets.UTF_8));+ webSocket.writeBinaryMessage(Buffer.buffer(response.encode()));+ }++ AgentMessage next() throws InterruptedException {+ AgentMessage message = received.poll(30, TimeUnit.SECONDS);+ assertNotNull(message, "the agent must send a frame");+ return message;+ }++ /** Collects output frames until the expected text shows up or the channel goes quiet. */+ String readUntil(String expected) throws InterruptedException {+ StringBuilder output = new StringBuilder();+ long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(30);+ while (System.nanoTime() < deadline && !output.toString().contains(expected)) {+ AgentMessage message = received.poll(1, TimeUnit.SECONDS);+ if (message == null) {+ continue;+ }+ if (AgentMessage.OUTPUT_STREAM_DATA.equals(message.messageType())+ && message.payloadType() == AgentMessage.PAYLOAD_OUTPUT) {+ output.append(message.payloadAsString());+ }+ }+ return output.toString();+ }++ void close() {+ if (webSocket != null) {+ webSocket.close();+ }+ if (httpClient != null) {+ httpClient.close();+ }+ }+ }++ private boolean isDockerAvailable() {+ try {+ dockerClient.pingCmd().exec();+ return true;+ } catch (RuntimeException e) {+ return false;+ }+ }+}diff --git a/src/test/java/io/github/hectorvent/floci/services/ecs/exec/EcsExecSessionRegistryTest.java b/src/test/java/io/github/hectorvent/floci/services/ecs/exec/EcsExecSessionRegistryTest.javanew file mode 100644index 0000000000..4d15c11905--- /dev/null+++ b/src/test/java/io/github/hectorvent/floci/services/ecs/exec/EcsExecSessionRegistryTest.java@@ -0,0 +1,133 @@+package io.github.hectorvent.floci.services.ecs.exec;++import io.github.hectorvent.floci.testing.MutableClock;+import org.junit.jupiter.api.Test;++import java.util.List;+import java.util.Optional;++import static org.junit.jupiter.api.Assertions.assertEquals;+import static org.junit.jupiter.api.Assertions.assertFalse;+import static org.junit.jupiter.api.Assertions.assertNotEquals;+import static org.junit.jupiter.api.Assertions.assertTrue;++/**+ * The token gate in front of an interactive shell. A session is claimed once, by the exact token+ * that was minted for it, never by a replay of that token, and never once it has outlived its TTL.+ */+class EcsExecSessionRegistryTest {++ private static final String TASK_ARN =+ "arn:aws:ecs:us-east-1:000000000000:task/my-cluster/0123456789abcdef";+ private static final String CLUSTER_ARN =+ "arn:aws:ecs:us-east-1:000000000000:cluster/my-cluster";++ private final MutableClock clock = new MutableClock();+ private final EcsExecSessionRegistry registry = new EcsExecSessionRegistry(clock);++ @Test+ void claimWithTheMintedToken() {+ ExecSession created = mint();++ Optional<ExecSession> claimed = registry.claim(created.sessionId(), created.tokenValue());++ assertTrue(claimed.isPresent());+ assertEquals("deadbeef", claimed.get().runtimeId());+ assertEquals(List.of("/bin/sh"), claimed.get().command());+ }++ @Test+ void claim_wrongToken_isRejectedAndLeavesTheSession() {+ ExecSession created = mint();++ assertTrue(registry.claim(created.sessionId(), "not-the-token").isEmpty());+ assertTrue(registry.find(created.sessionId()).isPresent(),+ "a failed claim must not let a stranger cancel somebody else's session");+ assertTrue(registry.claim(created.sessionId(), created.tokenValue()).isPresent());+ }++ @Test+ void claim_tokenOfADifferentLength_isRejected() {+ ExecSession created = mint();++ assertTrue(registry.claim(created.sessionId(), created.tokenValue() + "x").isEmpty());+ assertTrue(registry.claim(created.sessionId(), "").isEmpty());+ }++ @Test+ void claim_missingToken_isRejected() {+ ExecSession created = mint();++ assertTrue(registry.claim(created.sessionId(), null).isEmpty());+ }++ @Test+ void claim_unknownSession_isRejected() {+ assertTrue(registry.claim("ecs-execute-command-nothingtoseehere", "any").isEmpty());+ }++ @Test+ void claim_isSingleUse() {+ ExecSession created = mint();++ assertTrue(registry.claim(created.sessionId(), created.tokenValue()).isPresent());+ assertTrue(registry.claim(created.sessionId(), created.tokenValue()).isEmpty(),+ "a replayed token must not open a second channel");+ assertTrue(registry.find(created.sessionId()).isEmpty());+ }++ @Test+ void everySessionGetsItsOwnToken() {+ ExecSession first = mint();+ ExecSession second = mint();++ assertNotEquals(first.sessionId(), second.sessionId());+ assertNotEquals(first.tokenValue(), second.tokenValue());+ assertTrue(registry.claim(first.sessionId(), second.tokenValue()).isEmpty());+ }++ @Test+ void clearDropsEveryOpenSession() {+ ExecSession created = mint();++ registry.clear();++ assertFalse(registry.find(created.sessionId()).isPresent());+ }++ @Test+ void claim_sessionPastItsTtl_isRejected() {+ ExecSession created = mint();++ clock.advance(EcsExecSessionRegistry.SESSION_TTL.plusSeconds(1));++ assertTrue(registry.claim(created.sessionId(), created.tokenValue()).isEmpty(),+ "a session nobody connected to must stop being claimable once it expires");+ assertTrue(registry.find(created.sessionId()).isEmpty(),+ "an expired session must be dropped, not left holding its token");+ }++ @Test+ void claim_sessionWithinItsTtl_stillWorks() {+ ExecSession created = mint();++ clock.advance(EcsExecSessionRegistry.SESSION_TTL.minusSeconds(1));++ assertTrue(registry.claim(created.sessionId(), created.tokenValue()).isPresent());+ }++ @Test+ void find_sessionPastItsTtl_isEmpty() {+ ExecSession created = mint();++ clock.advance(EcsExecSessionRegistry.SESSION_TTL.plusSeconds(1));++ assertTrue(registry.find(created.sessionId()).isEmpty(),+ "the channel upgrade must refuse an expired session instead of opening a channel");+ }++ private ExecSession mint() {+ return registry.create(TASK_ARN, CLUSTER_ARN, "app",+ TASK_ARN.replace(":task/", ":container/"), "deadbeef", List.of("/bin/sh"), true);+ }+}