From 0ac746fabbe9d4434c0e5c18c563992658feb9d7 Mon Sep 17 00:00:00 2001
From: Sebastiaan van Stijn <github@gone.nl>
Date: Fri, 11 Feb 2022 22:44:42 +0100
Subject: [PATCH 1/6] api/swagger: update /containers/{id}/wait "condition"
 parameter to match code

This patch updates the swagger, and:

- adds an enum definition to document valid values (instead of describing them)
- updates the description to mention both "omitted" and "empty" values (although
  the former is already implicitly covered by the field being "optional" and
  having a default value).

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
---
 api/swagger.yaml | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/api/swagger.yaml b/api/swagger.yaml
index 46505d06c0..8cb8c9cbd1 100644
--- a/api/swagger.yaml
+++ b/api/swagger.yaml
@@ -7038,9 +7038,14 @@ paths:
         - name: "condition"
           in: "query"
           description: |
-            Wait until a container state reaches the given condition, either
-            'not-running' (default), 'next-exit', or 'removed'.
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:

From 0e5929f99dd4b0a4896dc21a93f33654714b58d3 Mon Sep 17 00:00:00 2001
From: Sebastiaan van Stijn <github@gone.nl>
Date: Mon, 14 Feb 2022 10:23:57 +0100
Subject: [PATCH 2/6] api/swagger: add missing 400 response for POST
 /containers/{id}/wait

The /containers/{id}/wait can return a 400 (invalid argument) error if
httputils.ParseForm() fails.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
---
 api/swagger.yaml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/api/swagger.yaml b/api/swagger.yaml
index 8cb8c9cbd1..49dda13769 100644
--- a/api/swagger.yaml
+++ b/api/swagger.yaml
@@ -7018,6 +7018,10 @@ paths:
                   Message:
                     description: "Details of an error"
                     type: "string"
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:

From 41b137962d0844bf2bf8e6c7f9786ab92306b06b Mon Sep 17 00:00:00 2001
From: Sebastiaan van Stijn <github@gone.nl>
Date: Fri, 11 Feb 2022 22:52:07 +0100
Subject: [PATCH 3/6] docs/api: update /containers/{id}/wait "condition"
 parameter (v1.30-v1.41)

This patch updates the swagger, and:

- adds an enum definition to document valid values (instead of describing them)
- updates the description to mention both "omitted" and "empty" values (although
  the former is already implicitly covered by the field being "optional" and
  having a default value).

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
---
 docs/api/v1.30.yaml | 9 ++++++++-
 docs/api/v1.31.yaml | 9 ++++++++-
 docs/api/v1.32.yaml | 9 ++++++++-
 docs/api/v1.33.yaml | 9 ++++++++-
 docs/api/v1.34.yaml | 9 ++++++++-
 docs/api/v1.35.yaml | 9 ++++++++-
 docs/api/v1.36.yaml | 9 ++++++++-
 docs/api/v1.37.yaml | 9 ++++++++-
 docs/api/v1.38.yaml | 9 ++++++++-
 docs/api/v1.39.yaml | 9 +++++++--
 docs/api/v1.40.yaml | 9 +++++++--
 docs/api/v1.41.yaml | 9 +++++++--
 12 files changed, 93 insertions(+), 15 deletions(-)

diff --git a/docs/api/v1.30.yaml b/docs/api/v1.30.yaml
index 27e37c690f..21aca3c534 100644
--- a/docs/api/v1.30.yaml
+++ b/docs/api/v1.30.yaml
@@ -4408,8 +4408,15 @@ paths:
           type: "string"
         - name: "condition"
           in: "query"
-          description: "Wait until a container state reaches the given condition, either 'not-running' (default), 'next-exit', or 'removed'."
+          description: |
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:
diff --git a/docs/api/v1.31.yaml b/docs/api/v1.31.yaml
index b2e50e3bd1..1ed5a2d205 100644
--- a/docs/api/v1.31.yaml
+++ b/docs/api/v1.31.yaml
@@ -4478,8 +4478,15 @@ paths:
           type: "string"
         - name: "condition"
           in: "query"
-          description: "Wait until a container state reaches the given condition, either 'not-running' (default), 'next-exit', or 'removed'."
+          description: |
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:
diff --git a/docs/api/v1.32.yaml b/docs/api/v1.32.yaml
index e6d5d62a86..30cefec10a 100644
--- a/docs/api/v1.32.yaml
+++ b/docs/api/v1.32.yaml
@@ -5715,8 +5715,15 @@ paths:
           type: "string"
         - name: "condition"
           in: "query"
-          description: "Wait until a container state reaches the given condition, either 'not-running' (default), 'next-exit', or 'removed'."
+          description: |
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:
diff --git a/docs/api/v1.33.yaml b/docs/api/v1.33.yaml
index e6c671660a..948c56f568 100644
--- a/docs/api/v1.33.yaml
+++ b/docs/api/v1.33.yaml
@@ -5720,8 +5720,15 @@ paths:
           type: "string"
         - name: "condition"
           in: "query"
-          description: "Wait until a container state reaches the given condition, either 'not-running' (default), 'next-exit', or 'removed'."
+          description: |
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:
diff --git a/docs/api/v1.34.yaml b/docs/api/v1.34.yaml
index ebea935440..787001add3 100644
--- a/docs/api/v1.34.yaml
+++ b/docs/api/v1.34.yaml
@@ -5756,8 +5756,15 @@ paths:
           type: "string"
         - name: "condition"
           in: "query"
-          description: "Wait until a container state reaches the given condition, either 'not-running' (default), 'next-exit', or 'removed'."
+          description: |
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:
diff --git a/docs/api/v1.35.yaml b/docs/api/v1.35.yaml
index 1193b267a1..0e86d89f7c 100644
--- a/docs/api/v1.35.yaml
+++ b/docs/api/v1.35.yaml
@@ -5743,8 +5743,15 @@ paths:
           type: "string"
         - name: "condition"
           in: "query"
-          description: "Wait until a container state reaches the given condition, either 'not-running' (default), 'next-exit', or 'removed'."
+          description: |
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:
diff --git a/docs/api/v1.36.yaml b/docs/api/v1.36.yaml
index 1f6350ffc8..f08773de55 100644
--- a/docs/api/v1.36.yaml
+++ b/docs/api/v1.36.yaml
@@ -5767,8 +5767,15 @@ paths:
           type: "string"
         - name: "condition"
           in: "query"
-          description: "Wait until a container state reaches the given condition, either 'not-running' (default), 'next-exit', or 'removed'."
+          description: |
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:
diff --git a/docs/api/v1.37.yaml b/docs/api/v1.37.yaml
index fbfd1a3d36..8348a79fb1 100644
--- a/docs/api/v1.37.yaml
+++ b/docs/api/v1.37.yaml
@@ -5794,8 +5794,15 @@ paths:
           type: "string"
         - name: "condition"
           in: "query"
-          description: "Wait until a container state reaches the given condition, either 'not-running' (default), 'next-exit', or 'removed'."
+          description: |
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:
diff --git a/docs/api/v1.38.yaml b/docs/api/v1.38.yaml
index 40661c0da4..33be2f5630 100644
--- a/docs/api/v1.38.yaml
+++ b/docs/api/v1.38.yaml
@@ -5855,8 +5855,15 @@ paths:
           type: "string"
         - name: "condition"
           in: "query"
-          description: "Wait until a container state reaches the given condition, either 'not-running' (default), 'next-exit', or 'removed'."
+          description: |
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:
diff --git a/docs/api/v1.39.yaml b/docs/api/v1.39.yaml
index 318c780c81..7be15161d1 100644
--- a/docs/api/v1.39.yaml
+++ b/docs/api/v1.39.yaml
@@ -6572,9 +6572,14 @@ paths:
         - name: "condition"
           in: "query"
           description: |
-            Wait until a container state reaches the given condition, either
-            'not-running' (default), 'next-exit', or 'removed'.
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:
diff --git a/docs/api/v1.40.yaml b/docs/api/v1.40.yaml
index a1c91c12d9..6606c4805f 100644
--- a/docs/api/v1.40.yaml
+++ b/docs/api/v1.40.yaml
@@ -6710,9 +6710,14 @@ paths:
         - name: "condition"
           in: "query"
           description: |
-            Wait until a container state reaches the given condition, either
-            'not-running' (default), 'next-exit', or 'removed'.
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:
diff --git a/docs/api/v1.41.yaml b/docs/api/v1.41.yaml
index 5c8327d69e..cc4581b7bc 100644
--- a/docs/api/v1.41.yaml
+++ b/docs/api/v1.41.yaml
@@ -6878,9 +6878,14 @@ paths:
         - name: "condition"
           in: "query"
           description: |
-            Wait until a container state reaches the given condition, either
-            'not-running' (default), 'next-exit', or 'removed'.
+            Wait until a container state reaches the given condition.
+
+            Defaults to `not-running` if omitted or empty.
           type: "string"
+          enum:
+            - "not-running"
+            - "next-exit"
+            - "removed"
           default: "not-running"
       tags: ["Container"]
   /containers/{id}:

From 5e2b7dea02e880ec5b8220251230409094345ff1 Mon Sep 17 00:00:00 2001
From: Sebastiaan van Stijn <github@gone.nl>
Date: Mon, 14 Feb 2022 12:42:08 +0100
Subject: [PATCH 4/6] docs/api: add missing 400 response for POST
 /containers/{id}/wait

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
---
 docs/api/v1.30.yaml | 4 ++++
 docs/api/v1.31.yaml | 4 ++++
 docs/api/v1.32.yaml | 4 ++++
 docs/api/v1.33.yaml | 4 ++++
 docs/api/v1.34.yaml | 4 ++++
 docs/api/v1.35.yaml | 4 ++++
 docs/api/v1.36.yaml | 4 ++++
 docs/api/v1.37.yaml | 4 ++++
 docs/api/v1.38.yaml | 4 ++++
 docs/api/v1.39.yaml | 4 ++++
 docs/api/v1.40.yaml | 4 ++++
 docs/api/v1.41.yaml | 4 ++++
 12 files changed, 48 insertions(+)

diff --git a/docs/api/v1.30.yaml b/docs/api/v1.30.yaml
index 21aca3c534..925fce5229 100644
--- a/docs/api/v1.30.yaml
+++ b/docs/api/v1.30.yaml
@@ -4389,6 +4389,10 @@ paths:
                 description: "Exit code of the container"
                 type: "integer"
                 x-nullable: false
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
diff --git a/docs/api/v1.31.yaml b/docs/api/v1.31.yaml
index 1ed5a2d205..152e4a9f25 100644
--- a/docs/api/v1.31.yaml
+++ b/docs/api/v1.31.yaml
@@ -4459,6 +4459,10 @@ paths:
                 description: "Exit code of the container"
                 type: "integer"
                 x-nullable: false
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
diff --git a/docs/api/v1.32.yaml b/docs/api/v1.32.yaml
index 30cefec10a..914928e04f 100644
--- a/docs/api/v1.32.yaml
+++ b/docs/api/v1.32.yaml
@@ -5696,6 +5696,10 @@ paths:
                 description: "Exit code of the container"
                 type: "integer"
                 x-nullable: false
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
diff --git a/docs/api/v1.33.yaml b/docs/api/v1.33.yaml
index 948c56f568..0e98c983ad 100644
--- a/docs/api/v1.33.yaml
+++ b/docs/api/v1.33.yaml
@@ -5701,6 +5701,10 @@ paths:
                 description: "Exit code of the container"
                 type: "integer"
                 x-nullable: false
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
diff --git a/docs/api/v1.34.yaml b/docs/api/v1.34.yaml
index 787001add3..06f6bc192e 100644
--- a/docs/api/v1.34.yaml
+++ b/docs/api/v1.34.yaml
@@ -5737,6 +5737,10 @@ paths:
                   Message:
                     description: "Details of an error"
                     type: "string"
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
diff --git a/docs/api/v1.35.yaml b/docs/api/v1.35.yaml
index 0e86d89f7c..eb0905e276 100644
--- a/docs/api/v1.35.yaml
+++ b/docs/api/v1.35.yaml
@@ -5724,6 +5724,10 @@ paths:
                   Message:
                     description: "Details of an error"
                     type: "string"
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
diff --git a/docs/api/v1.36.yaml b/docs/api/v1.36.yaml
index f08773de55..c1b42aeecc 100644
--- a/docs/api/v1.36.yaml
+++ b/docs/api/v1.36.yaml
@@ -5748,6 +5748,10 @@ paths:
                   Message:
                     description: "Details of an error"
                     type: "string"
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
diff --git a/docs/api/v1.37.yaml b/docs/api/v1.37.yaml
index 8348a79fb1..910e283319 100644
--- a/docs/api/v1.37.yaml
+++ b/docs/api/v1.37.yaml
@@ -5775,6 +5775,10 @@ paths:
                   Message:
                     description: "Details of an error"
                     type: "string"
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
diff --git a/docs/api/v1.38.yaml b/docs/api/v1.38.yaml
index 33be2f5630..96fff9027b 100644
--- a/docs/api/v1.38.yaml
+++ b/docs/api/v1.38.yaml
@@ -5836,6 +5836,10 @@ paths:
                   Message:
                     description: "Details of an error"
                     type: "string"
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
diff --git a/docs/api/v1.39.yaml b/docs/api/v1.39.yaml
index 7be15161d1..45b72a8df3 100644
--- a/docs/api/v1.39.yaml
+++ b/docs/api/v1.39.yaml
@@ -6552,6 +6552,10 @@ paths:
                   Message:
                     description: "Details of an error"
                     type: "string"
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
diff --git a/docs/api/v1.40.yaml b/docs/api/v1.40.yaml
index 6606c4805f..85a5f30e17 100644
--- a/docs/api/v1.40.yaml
+++ b/docs/api/v1.40.yaml
@@ -6690,6 +6690,10 @@ paths:
                   Message:
                     description: "Details of an error"
                     type: "string"
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:
diff --git a/docs/api/v1.41.yaml b/docs/api/v1.41.yaml
index cc4581b7bc..94b79f9780 100644
--- a/docs/api/v1.41.yaml
+++ b/docs/api/v1.41.yaml
@@ -6858,6 +6858,10 @@ paths:
                   Message:
                     description: "Details of an error"
                     type: "string"
+        400:
+          description: "bad parameter"
+          schema:
+            $ref: "#/definitions/ErrorResponse"
         404:
           description: "no such container"
           schema:

From a832635e5135eb82fe6cd0698f533ae9426eeb40 Mon Sep 17 00:00:00 2001
From: Sebastiaan van Stijn <github@gone.nl>
Date: Fri, 11 Feb 2022 22:54:20 +0100
Subject: [PATCH 5/6] client.ContainerWait(): don't send empty "condition"
 query parameter

The client would always send a value, even if no `condition` was set;

    Calling POST /v1.41/containers/foo/wait?condition=

This patch changes the client to not send the parameter if it's empty (and the
API default value should be used).

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
---
 client/container_wait.go | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/client/container_wait.go b/client/container_wait.go
index 6ab8c1da96..e9b134c9d2 100644
--- a/client/container_wait.go
+++ b/client/container_wait.go
@@ -33,7 +33,9 @@ func (cli *Client) ContainerWait(ctx context.Context, containerID string, condit
 	errC := make(chan error, 1)
 
 	query := url.Values{}
-	query.Set("condition", string(condition))
+	if condition != "" {
+		query.Set("condition", string(condition))
+	}
 
 	resp, err := cli.post(ctx, "/containers/"+containerID+"/wait", query, nil, nil)
 	if err != nil {

From 737e8c6ab81842d61d86df3efec5f505b5484d4c Mon Sep 17 00:00:00 2001
From: Sebastiaan van Stijn <github@gone.nl>
Date: Mon, 14 Feb 2022 10:29:29 +0100
Subject: [PATCH 6/6] api: POST /containers/{id}/wait: validate "condition"
 parameter

The endpoint was silently ignoring invalid values for the "condition" parameter.
This patch now returns a 400 status if an unknown, non-empty "condition" is passed.

With this patch:

    curl --unix-socket /var/run/docker.sock -XPOST 'http://localhost/v1.41/containers/foo/wait?condition=foobar'
    {"message":"invalid condition: \"foobar\""}

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
---
 api/server/router/container/container_routes.go | 16 ++++++++++------
 docs/api/version-history.md                     |  2 ++
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/api/server/router/container/container_routes.go b/api/server/router/container/container_routes.go
index c3074aa3a0..dbaa43da63 100644
--- a/api/server/router/container/container_routes.go
+++ b/api/server/router/container/container_routes.go
@@ -336,12 +336,16 @@ func (s *containerRouter) postContainersWait(ctx context.Context, w http.Respons
 		if err := httputils.ParseForm(r); err != nil {
 			return err
 		}
-		switch container.WaitCondition(r.Form.Get("condition")) {
-		case container.WaitConditionNextExit:
-			waitCondition = containerpkg.WaitConditionNextExit
-		case container.WaitConditionRemoved:
-			waitCondition = containerpkg.WaitConditionRemoved
-			legacyRemovalWaitPre134 = versions.LessThan(version, "1.34")
+		if v := r.Form.Get("condition"); v != "" {
+			switch container.WaitCondition(v) {
+			case container.WaitConditionNextExit:
+				waitCondition = containerpkg.WaitConditionNextExit
+			case container.WaitConditionRemoved:
+				waitCondition = containerpkg.WaitConditionRemoved
+				legacyRemovalWaitPre134 = versions.LessThan(version, "1.34")
+			default:
+				return errdefs.InvalidParameter(errors.Errorf("invalid condition: %q", v))
+			}
 		}
 	}
 
diff --git a/docs/api/version-history.md b/docs/api/version-history.md
index d6e44c4bbc..0a8041812a 100644
--- a/docs/api/version-history.md
+++ b/docs/api/version-history.md
@@ -40,6 +40,8 @@ keywords: "API, Docker, rcli, REST, documentation"
   was used and the architecture was ignored. If no `platform` option is set, the
   host's operating system and architecture as used as default. This change is not
   versioned, and affects all API versions if the daemon has this patch.
+* The `POST /containers/{id}/wait` endpoint now returns a `400` status code if an
+  invalid `condition` is provided (on API 1.30 and up).
 
 ## v1.41 API changes