From 85ec0bec0d484ccac93297779044ab6deaed8fb1 Mon Sep 17 00:00:00 2001
From: Alexander Koshevoy <alexander.koshevoy@jetbrains.com>
Date: Mon, 4 Aug 2025 22:20:49 +0200
Subject: [PATCH 1/2] Add support for container wait conditions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Expose the `condition` query parameter (added in Docker Engine API v1.30) on `WaitContainerCmd`. When the parameter is omitted, we keep the daemon’s default `not-running` behaviour.

Practical implications
----------------------
* **create → wait (no condition) → start**
  Calling `wait` right after `create` but **before** `start` returns immediately with whatever exit-code the daemon reports for a container that has never run (typically `0`). In other words, you learn nothing about the future process.

* **create → start → wait (no condition)**
  For short-lived containers started with `--rm`, the container may be auto-removed before the client manages to issue `wait`, resulting in a *"container not found"* error.

* **create → wait(condition=removed) → start**
  Passing the new `removed` condition eliminates both races: the wait call blocks until the container has exited *and* been removed, reliably yielding the actual exit code even for `--rm` containers.
---
 .../api/command/WaitContainerCmd.java         | 18 +++-
 .../api/model/WaitContainerCondition.java     | 26 ++++++
 .../core/command/WaitContainerCmdImpl.java    | 17 ++++
 .../core/exec/WaitContainerCmdExec.java       |  6 ++
 .../dockerjava/cmd/WaitContainerCmdIT.java    | 84 ++++++++++++++++++-
 5 files changed, 147 insertions(+), 4 deletions(-)
 create mode 100644 docker-java-api/src/main/java/com/github/dockerjava/api/model/WaitContainerCondition.java

diff --git a/docker-java-api/src/main/java/com/github/dockerjava/api/command/WaitContainerCmd.java b/docker-java-api/src/main/java/com/github/dockerjava/api/command/WaitContainerCmd.java
index 3117cf7e4..7b910cd69 100644
--- a/docker-java-api/src/main/java/com/github/dockerjava/api/command/WaitContainerCmd.java
+++ b/docker-java-api/src/main/java/com/github/dockerjava/api/command/WaitContainerCmd.java
@@ -2,9 +2,11 @@
 
 import javax.annotation.CheckForNull;
 import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 
 import com.github.dockerjava.api.async.ResultCallback;
 import com.github.dockerjava.api.exception.NotFoundException;
+import com.github.dockerjava.api.model.WaitContainerCondition;
 import com.github.dockerjava.api.model.WaitResponse;
 
 /**
@@ -20,8 +22,20 @@ public interface WaitContainerCmd extends AsyncDockerCmd<WaitContainerCmd, WaitR
     WaitContainerCmd withContainerId(@Nonnull String containerId);
 
     /**
-     * @throws NotFoundException
-     *             container not found
+     * Defaults to {@link WaitContainerCondition#NOT_RUNNING} if omitted or empty.
+     *
+     * @since {@link RemoteApiVersion#VERSION_1_30}
+     */
+    @Nullable
+    WaitContainerCondition getCondition();
+
+    /**
+     * @since {@link RemoteApiVersion#VERSION_1_30}
+     */
+    WaitContainerCmd withCondition(@Nullable WaitContainerCondition condition);
+
+    /**
+     * @throws NotFoundException container not found
      */
     @Override
     <T extends ResultCallback<WaitResponse>> T exec(T resultCallback);
diff --git a/docker-java-api/src/main/java/com/github/dockerjava/api/model/WaitContainerCondition.java b/docker-java-api/src/main/java/com/github/dockerjava/api/model/WaitContainerCondition.java
new file mode 100644
index 000000000..8af0efa35
--- /dev/null
+++ b/docker-java-api/src/main/java/com/github/dockerjava/api/model/WaitContainerCondition.java
@@ -0,0 +1,26 @@
+package com.github.dockerjava.api.model;
+
+import javax.annotation.Nonnull;
+
+/**
+ * Docker Engine API <em>wait</em> conditions (added in v1.30).
+ *
+ * @since {@link RemoteApiVersion#VERSION_1_30}
+ */
+public enum WaitContainerCondition {
+    NOT_RUNNING("not-running"),
+    NEXT_EXIT("next-exit"),
+    REMOVED("removed");
+
+    @Nonnull
+    private final String value;
+
+    WaitContainerCondition(@Nonnull String value) {
+        this.value = value;
+    }
+
+    @Nonnull
+    public String getValue() {
+        return value;
+    }
+}
diff --git a/docker-java-core/src/main/java/com/github/dockerjava/core/command/WaitContainerCmdImpl.java b/docker-java-core/src/main/java/com/github/dockerjava/core/command/WaitContainerCmdImpl.java
index 91b2255bc..b627e2ccd 100644
--- a/docker-java-core/src/main/java/com/github/dockerjava/core/command/WaitContainerCmdImpl.java
+++ b/docker-java-core/src/main/java/com/github/dockerjava/core/command/WaitContainerCmdImpl.java
@@ -2,7 +2,10 @@
 
 import java.util.Objects;
 
+import javax.annotation.Nullable;
+
 import com.github.dockerjava.api.command.WaitContainerCmd;
+import com.github.dockerjava.api.model.WaitContainerCondition;
 import com.github.dockerjava.api.model.WaitResponse;
 
 /**
@@ -15,6 +18,8 @@ public class WaitContainerCmdImpl extends AbstrAsyncDockerCmd<WaitContainerCmd,
 
     private String containerId;
 
+    private WaitContainerCondition condition;
+
     public WaitContainerCmdImpl(WaitContainerCmd.Exec exec, String containerId) {
         super(exec);
         withContainerId(containerId);
@@ -31,4 +36,16 @@ public WaitContainerCmd withContainerId(String containerId) {
         return this;
     }
 
+    @Nullable
+    @Override
+    public WaitContainerCondition getCondition() {
+        return condition;
+    }
+
+    @Override
+    public WaitContainerCmd withCondition(@Nullable WaitContainerCondition condition) {
+        this.condition = condition;
+        return this;
+    }
+
 }
diff --git a/docker-java-core/src/main/java/com/github/dockerjava/core/exec/WaitContainerCmdExec.java b/docker-java-core/src/main/java/com/github/dockerjava/core/exec/WaitContainerCmdExec.java
index 57cc727fe..3d2b2fa8e 100644
--- a/docker-java-core/src/main/java/com/github/dockerjava/core/exec/WaitContainerCmdExec.java
+++ b/docker-java-core/src/main/java/com/github/dockerjava/core/exec/WaitContainerCmdExec.java
@@ -1,5 +1,6 @@
 package com.github.dockerjava.core.exec;
 
+import com.github.dockerjava.api.model.WaitContainerCondition;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -25,6 +26,11 @@ protected Void execute0(WaitContainerCmd command, ResultCallback<WaitResponse> r
         WebTarget webTarget = getBaseResource().path("/containers/{id}/wait").resolveTemplate("id",
                 command.getContainerId());
 
+        WaitContainerCondition condition = command.getCondition();
+        if (condition != null) {
+            webTarget = webTarget.queryParam("condition", condition.getValue());
+        }
+
         LOGGER.trace("POST: {}", webTarget);
 
         webTarget.request().accept(MediaType.APPLICATION_JSON).post((Object) null, new TypeReference<WaitResponse>() {
diff --git a/docker-java/src/test/java/com/github/dockerjava/cmd/WaitContainerCmdIT.java b/docker-java/src/test/java/com/github/dockerjava/cmd/WaitContainerCmdIT.java
index e2ad2a643..76fb32be5 100644
--- a/docker-java/src/test/java/com/github/dockerjava/cmd/WaitContainerCmdIT.java
+++ b/docker-java/src/test/java/com/github/dockerjava/cmd/WaitContainerCmdIT.java
@@ -8,18 +8,25 @@
 import com.github.dockerjava.api.exception.DockerClientException;
 import com.github.dockerjava.api.exception.DockerException;
 import com.github.dockerjava.api.exception.NotFoundException;
+import com.github.dockerjava.api.model.WaitContainerCondition;
 import com.github.dockerjava.api.model.WaitResponse;
+import org.junit.Assert;
 import org.junit.Test;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import java.util.concurrent.TimeUnit;
 
+import static com.github.dockerjava.api.model.HostConfig.newHostConfig;
+import static com.github.dockerjava.core.RemoteApiVersion.VERSION_1_25;
+import static com.github.dockerjava.core.RemoteApiVersion.VERSION_1_30;
+import static com.github.dockerjava.junit.DockerMatchers.isGreaterOrEqual;
 import static org.hamcrest.MatcherAssert.assertThat;
 import static org.hamcrest.Matchers.equalTo;
 import static org.hamcrest.Matchers.is;
 import static org.hamcrest.Matchers.emptyString;
 import static org.hamcrest.Matchers.not;
+import static org.junit.Assume.assumeThat;
 
 public class WaitContainerCmdIT extends CmdIT {
     public static final Logger LOG = LoggerFactory.getLogger(BuildImageCmd.class);
@@ -35,7 +42,7 @@ public void testWaitContainer() throws DockerException {
         dockerRule.getClient().startContainerCmd(container.getId()).exec();
 
         int exitCode = dockerRule.getClient().waitContainerCmd(container.getId()).start()
-                .awaitStatusCode();
+            .awaitStatusCode();
         LOG.info("Container exit code: {}", exitCode);
 
         assertThat(exitCode, equalTo(0));
@@ -94,7 +101,7 @@ public void testWaitContainerTimeout() {
         dockerRule.getClient().startContainerCmd(container.getId()).exec();
 
         WaitContainerResultCallback callback = dockerRule.getClient().waitContainerCmd(container.getId()).exec(
-                new WaitContainerResultCallback());
+            new WaitContainerResultCallback());
         try {
             callback.awaitStatusCode(100, TimeUnit.MILLISECONDS);
             throw new AssertionError("Should throw exception on timeout.");
@@ -102,4 +109,77 @@ public void testWaitContainerTimeout() {
             LOG.info(e.getMessage());
         }
     }
+
+    @Test
+    public void testWaitNotStartedContainer() {
+        assumeThat("API version should be > 1.25", dockerRule, isGreaterOrEqual(VERSION_1_25));
+
+        CreateContainerResponse container = dockerRule.getClient().createContainerCmd("busybox")
+            .withHostConfig(newHostConfig().withAutoRemove(true))
+            .exec();
+
+        LOG.info("Created container: {}", container.toString());
+        assertThat(container.getId(), not(is(emptyString())));
+
+        WaitContainerResultCallback callback = dockerRule.getClient().waitContainerCmd(container.getId()).exec(new WaitContainerResultCallback());
+
+        Integer statusCode = callback.awaitStatusCode(100, TimeUnit.MILLISECONDS);
+        Assert.assertEquals(0, statusCode.intValue());
+    }
+
+    @Test
+    public void testWaitContainerWithAutoRemoval() {
+        assumeThat("API version should be > 1.30", dockerRule, isGreaterOrEqual(VERSION_1_30));
+
+        CreateContainerResponse container = dockerRule.getClient().createContainerCmd("busybox")
+            .withCmd("false")
+            .withHostConfig(newHostConfig().withAutoRemove(true))
+            .exec();
+
+        LOG.info("Created container: {}", container.toString());
+        assertThat(container.getId(), not(is(emptyString())));
+
+        WaitContainerResultCallback removedCondition = dockerRule.getClient().waitContainerCmd(container.getId())
+            .withCondition(WaitContainerCondition.REMOVED)
+            .exec(new WaitContainerResultCallback());
+
+        WaitContainerResultCallback nextExitCondition = dockerRule.getClient().waitContainerCmd(container.getId())
+            .withCondition(WaitContainerCondition.NEXT_EXIT)
+            .exec(new WaitContainerResultCallback());
+
+        dockerRule.getClient().startContainerCmd(container.getId()).exec();
+
+        Assert.assertEquals(1, removedCondition.awaitStatusCode(100, TimeUnit.MILLISECONDS).intValue());
+        Assert.assertEquals(1, nextExitCondition.awaitStatusCode(100, TimeUnit.MILLISECONDS).intValue());
+    }
+
+    @Test
+    public void testWaitRestartedContainer() {
+        assumeThat("API version should be > 1.30", dockerRule, isGreaterOrEqual(VERSION_1_30));
+
+        CreateContainerResponse container = dockerRule.getClient().createContainerCmd("busybox")
+            .withCmd("sh", "-c", "[ -f \"$HOME/.first_run_marker\" ] && exit 2 || { touch \"$HOME/.first_run_marker\"; exit 1; }")
+            .exec();
+
+        LOG.info("Created container: {}", container.toString());
+        assertThat(container.getId(), not(is(emptyString())));
+
+        WaitContainerResultCallback firstExitCallback = dockerRule.getClient().waitContainerCmd(container.getId())
+            .withCondition(WaitContainerCondition.NEXT_EXIT)
+            .exec(new WaitContainerResultCallback());
+
+        dockerRule.getClient().startContainerCmd(container.getId()).exec();
+
+        Integer firstStatusCode = firstExitCallback.awaitStatusCode(100, TimeUnit.MILLISECONDS);
+        Assert.assertEquals(1, firstStatusCode.intValue());
+
+        WaitContainerResultCallback callback = dockerRule.getClient().waitContainerCmd(container.getId())
+            .withCondition(WaitContainerCondition.NEXT_EXIT)
+            .exec(new WaitContainerResultCallback());
+
+        dockerRule.getClient().startContainerCmd(container.getId()).exec();
+
+        Integer statusCode = callback.awaitStatusCode(100, TimeUnit.MILLISECONDS);
+        Assert.assertEquals(2, statusCode.intValue());
+    }
 }

From 4a1db74ba9f5f6fac4804e8c443f45e2c69a9305 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Edd=C3=BA=20Mel=C3=A9ndez?= <eddu.melendez@gmail.com>
Date: Tue, 19 Aug 2025 15:41:42 -0600
Subject: [PATCH 2/2] Polish

---
 .../java/com/github/dockerjava/cmd/WaitContainerCmdIT.java    | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docker-java/src/test/java/com/github/dockerjava/cmd/WaitContainerCmdIT.java b/docker-java/src/test/java/com/github/dockerjava/cmd/WaitContainerCmdIT.java
index 76fb32be5..3a39b3eea 100644
--- a/docker-java/src/test/java/com/github/dockerjava/cmd/WaitContainerCmdIT.java
+++ b/docker-java/src/test/java/com/github/dockerjava/cmd/WaitContainerCmdIT.java
@@ -42,7 +42,7 @@ public void testWaitContainer() throws DockerException {
         dockerRule.getClient().startContainerCmd(container.getId()).exec();
 
         int exitCode = dockerRule.getClient().waitContainerCmd(container.getId()).start()
-            .awaitStatusCode();
+                .awaitStatusCode();
         LOG.info("Container exit code: {}", exitCode);
 
         assertThat(exitCode, equalTo(0));
@@ -101,7 +101,7 @@ public void testWaitContainerTimeout() {
         dockerRule.getClient().startContainerCmd(container.getId()).exec();
 
         WaitContainerResultCallback callback = dockerRule.getClient().waitContainerCmd(container.getId()).exec(
-            new WaitContainerResultCallback());
+                new WaitContainerResultCallback());
         try {
             callback.awaitStatusCode(100, TimeUnit.MILLISECONDS);
             throw new AssertionError("Should throw exception on timeout.");