[grid] Minimum Docker API 1.44 for Docker Engine v29+ in Dynamic Grid (#16591)

Author: VietND96

java/src/org/openqa/selenium/docker/Docker.java

@@ -27,9 +27,22 @@ public class Docker {
   private static final Logger LOG = Logger.getLogger(Docker.class.getName());
   protected final HttpHandler client;
   private volatile Optional<DockerProtocol> dockerClient;
+  private final String apiVersion;
 
   public Docker(HttpHandler client) {
+    this(client, null);
+  }
+
+  /**
+   * Creates a Docker client with an optional API version override.
+   *
+   * @param client HTTP client for Docker communication
+   * @param apiVersion Optional API version to use (e.g., "1.41" or "1.44"). If null, the version
+   *     will be auto-detected.
+   */
+  public Docker(HttpHandler client, String apiVersion) {
     this.client = Require.nonNull("HTTP client", client);
+    this.apiVersion = apiVersion;
     this.dockerClient = Optional.empty();
   }
 
@@ -83,7 +96,11 @@ private Optional<DockerProtocol> getDocker() {
 
     synchronized (this) {
       if (!dockerClient.isPresent()) {
-        dockerClient = new VersionCommand(client).getDockerProtocol();
+        VersionCommand versionCommand = new VersionCommand(client);
+        dockerClient =
+            apiVersion != null
+                ? versionCommand.getDockerProtocol(apiVersion)
+                : versionCommand.getDockerProtocol();
       }
     }
 

java/src/org/openqa/selenium/docker/VersionCommand.java

@@ -25,7 +25,7 @@
 import java.util.Map;
 import java.util.Optional;
 import java.util.function.Function;
-import org.openqa.selenium.docker.v1_41.V141Docker;
+import org.openqa.selenium.docker.client.DockerClient;
 import org.openqa.selenium.internal.Require;
 import org.openqa.selenium.json.Json;
 import org.openqa.selenium.json.JsonException;
@@ -38,15 +38,50 @@ class VersionCommand {
 
   private static final Json JSON = new Json();
   // Insertion order matters, and is preserved by ImmutableMap.
+  // Map Docker API versions to their implementations
+  // 1.44 is the default for Docker Engine 29.0.0+
+  // 1.41 is maintained for backward compatibility with legacy engines
+  // Both use the same generic implementation with different API version strings
   private static final Map<Version, Function<HttpHandler, DockerProtocol>> SUPPORTED_VERSIONS =
-      ImmutableMap.of(new Version("1.40"), V141Docker::new);
+      ImmutableMap.of(
+          new Version("1.44"), client -> new DockerClient(client, "1.44"),
+          new Version("1.41"), client -> new DockerClient(client, "1.41"),
+          new Version("1.40"), client -> new DockerClient(client, "1.40"));
 
   private final HttpHandler handler;
 
   public VersionCommand(HttpHandler handler) {
     this.handler = Require.nonNull("HTTP client", handler);
   }
 
+  /**
+   * Gets the Docker protocol implementation for a user-specified API version. This allows users to
+   * override the automatic version detection and force a specific API version (e.g., 1.41 for
+   * legacy Docker engines).
+   *
+   * @param requestedVersion The API version to use (e.g., "1.41" or "1.44")
+   * @return Optional containing the DockerProtocol implementation if the version is supported
+   */
+  public Optional<DockerProtocol> getDockerProtocol(String requestedVersion) {
+    if (requestedVersion == null || requestedVersion.isEmpty()) {
+      return getDockerProtocol();
+    }
+
+    Version version = new Version(requestedVersion);
+    Function<HttpHandler, DockerProtocol> factory = SUPPORTED_VERSIONS.get(version);
+
+    if (factory != null) {
+      return Optional.of(factory.apply(handler));
+    }
+
+    // If exact version not found, try to find a compatible version
+    return SUPPORTED_VERSIONS.entrySet().stream()
+        .filter(entry -> entry.getKey().equalTo(version))
+        .map(Map.Entry::getValue)
+        .map(func -> func.apply(handler))
+        .findFirst();
+  }
+
   public Optional<DockerProtocol> getDockerProtocol() {
     try {
       HttpResponse res = handler.execute(new HttpRequest(GET, "/version"));

java/src/org/openqa/selenium/docker/client/AdapterFactory.java

@@ -0,0 +1,104 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package org.openqa.selenium.docker.client;
+
+import java.util.logging.Logger;
+
+/**
+ * Factory for creating API version-specific adapters.
+ *
+ * <p>This factory selects the appropriate adapter based on the Docker API version:
+ *
+ * <ul>
+ *   <li>API v1.40-1.43: Uses {@link V140Adapter}
+ *   <li>API v1.44+: Uses {@link V144Adapter}
+ * </ul>
+ *
+ * <p>The factory uses version comparison to determine which adapter to use, ensuring that future
+ * API versions (e.g., 1.45, 1.46) automatically use the most appropriate adapter.
+ */
+class AdapterFactory {
+
+  private static final Logger LOG = Logger.getLogger(AdapterFactory.class.getName());
+
+  /**
+   * Creates an appropriate adapter for the given API version.
+   *
+   * @param apiVersion The Docker API version (e.g., "1.40", "1.44")
+   * @return An adapter suitable for the specified API version
+   * @throws IllegalArgumentException if apiVersion is null or empty
+   */
+  public static ApiVersionAdapter createAdapter(String apiVersion) {
+    if (apiVersion == null || apiVersion.trim().isEmpty()) {
+      throw new IllegalArgumentException("API version cannot be null or empty");
+    }
+
+    // API v1.44+ uses the new adapter
+    if (compareVersions(apiVersion, "1.44") >= 0) {
+      LOG.fine("Using V144Adapter for API version " + apiVersion);
+      return new V144Adapter(apiVersion);
+    }
+
+    // API v1.40-1.43 uses the legacy adapter
+    LOG.fine("Using V140Adapter for API version " + apiVersion);
+    return new V140Adapter(apiVersion);
+  }
+
+  /**
+   * Compares two version strings in the format "major.minor".
+   *
+   * @param version1 First version string (e.g., "1.44")
+   * @param version2 Second version string (e.g., "1.44")
+   * @return negative if version1 < version2, zero if equal, positive if version1 > version2
+   */
+  private static int compareVersions(String version1, String version2) {
+    String[] parts1 = version1.split("\\.");
+    String[] parts2 = version2.split("\\.");
+
+    int major1 = Integer.parseInt(parts1[0]);
+    int minor1 = parts1.length > 1 ? Integer.parseInt(parts1[1]) : 0;
+
+    int major2 = Integer.parseInt(parts2[0]);
+    int minor2 = parts2.length > 1 ? Integer.parseInt(parts2[1]) : 0;
+
+    if (major1 != major2) {
+      return major1 - major2;
+    }
+    return minor1 - minor2;
+  }
+
+  /**
+   * Determines if the given API version supports multiple network endpoints.
+   *
+   * @param apiVersion The Docker API version
+   * @return true if multiple networks are supported, false otherwise
+   */
+  public static boolean supportsMultipleNetworks(String apiVersion) {
+    return createAdapter(apiVersion).supportsMultipleNetworks();
+  }
+
+  /**
+   * Determines if the given API version includes the VirtualSize field.
+   *
+   * @param apiVersion The Docker API version
+   * @return true if VirtualSize field is present, false otherwise
+   */
+  public static boolean hasVirtualSizeField(String apiVersion) {
+    return createAdapter(apiVersion).hasVirtualSizeField();
+  }
+}

java/src/org/openqa/selenium/docker/client/ApiVersionAdapter.java

@@ -0,0 +1,93 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package org.openqa.selenium.docker.client;
+
+import java.util.Map;
+
+/**
+ * Adapter interface for handling API version-specific differences in Docker Engine API.
+ *
+ * <p>Different Docker API versions may have subtle differences in request/response formats, field
+ * names, or behavior. Adapters provide a way to normalize these differences and ensure consistent
+ * behavior across API versions.
+ *
+ * <p>Key differences handled by adapters:
+ *
+ * <ul>
+ *   <li>v1.40-1.43: Uses {@code VirtualSize} field in image responses
+ *   <li>v1.44+: {@code VirtualSize} removed, use {@code Size} field instead
+ *   <li>v1.44+: Support for multiple network endpoints in container creation
+ *   <li>v1.44+: Enhanced validation for network creation
+ * </ul>
+ */
+interface ApiVersionAdapter {
+
+  /**
+   * Adapts an image response from the Docker API to normalize field names and structure.
+   *
+   * <p>Example: In API v1.44+, {@code VirtualSize} was removed. This method ensures that {@code
+   * Size} is always available regardless of API version.
+   *
+   * @param response The raw image response from Docker API
+   * @return Adapted response with normalized field names
+   */
+  Map<String, Object> adaptImageResponse(Map<String, Object> response);
+
+  /**
+   * Adapts a container creation request to match the target API version's expectations.
+   *
+   * <p>Example: API v1.44+ supports multiple network endpoints, while earlier versions only support
+   * a single network. This method ensures the request is formatted correctly.
+   *
+   * @param request The container creation request
+   * @return Adapted request compatible with the target API version
+   */
+  Map<String, Object> adaptContainerCreateRequest(Map<String, Object> request);
+
+  /**
+   * Adapts a container inspection response to normalize field names and structure.
+   *
+   * <p>Example: Some fields may be deprecated or renamed across versions. This method ensures
+   * consistent field names in the response.
+   *
+   * @param response The raw container inspection response from Docker API
+   * @return Adapted response with normalized field names
+   */
+  Map<String, Object> adaptContainerInspectResponse(Map<String, Object> response);
+
+  /**
+   * Returns whether this API version supports multiple network endpoints in container creation.
+   *
+   * @return true if multiple networks are supported, false otherwise
+   */
+  boolean supportsMultipleNetworks();
+
+  /**
+   * Returns whether this API version includes the VirtualSize field in image responses.
+   *
+   * @return true if VirtualSize field is present, false otherwise
+   */
+  boolean hasVirtualSizeField();
+
+  /**
+   * Returns the API version this adapter is designed for.
+   *
+   * @return API version string (e.g., "1.40", "1.44")
+   */
+  String getApiVersion();
+}

java/src/org/openqa/selenium/docker/v1_41/CreateContainer.java renamed to java/src/org/openqa/selenium/docker/client/CreateContainer.java

@@ -15,9 +15,9 @@
 // specific language governing permissions and limitations
 // under the License.
 
-package org.openqa.selenium.docker.v1_41;
+package org.openqa.selenium.docker.client;
 
-import static org.openqa.selenium.docker.v1_41.V141Docker.DOCKER_API_VERSION;
+import static org.openqa.selenium.docker.client.DockerClient.DOCKER_API_VERSION;
 import static org.openqa.selenium.json.Json.JSON_UTF_8;
 import static org.openqa.selenium.json.Json.MAP_TYPE;
 import static org.openqa.selenium.remote.http.Contents.asJson;
@@ -45,20 +45,38 @@ class CreateContainer {
   private static final Logger LOG = Logger.getLogger(CreateContainer.class.getName());
   private final DockerProtocol protocol;
   private final HttpHandler client;
+  private final String apiVersion;
+  private final ApiVersionAdapter adapter;
 
   public CreateContainer(DockerProtocol protocol, HttpHandler client) {
+    this(protocol, client, DOCKER_API_VERSION, AdapterFactory.createAdapter(DOCKER_API_VERSION));
+  }
+
+  public CreateContainer(DockerProtocol protocol, HttpHandler client, String apiVersion) {
+    this(protocol, client, apiVersion, AdapterFactory.createAdapter(apiVersion));
+  }
+
+  public CreateContainer(
+      DockerProtocol protocol, HttpHandler client, String apiVersion, ApiVersionAdapter adapter) {
     this.protocol = Require.nonNull("Protocol", protocol);
     this.client = Require.nonNull("HTTP client", client);
+    this.apiVersion = Require.nonNull("API version", apiVersion);
+    this.adapter = Require.nonNull("API version adapter", adapter);
   }
 
   public Container apply(ContainerConfig info) {
     this.protocol.getImage(info.getImage().getName());
+
+    // Convert ContainerConfig to JSON and adapt for API version
+    Map<String, Object> requestJson = JSON.toType(JSON.toJson(info), MAP_TYPE);
+    Map<String, Object> adaptedRequest = adapter.adaptContainerCreateRequest(requestJson);
+
     HttpResponse res =
         DockerMessages.throwIfNecessary(
             client.execute(
-                new HttpRequest(POST, String.format("/v%s/containers/create", DOCKER_API_VERSION))
+                new HttpRequest(POST, String.format("/v%s/containers/create", apiVersion))
                     .addHeader("Content-Type", JSON_UTF_8)
-                    .setContent(asJson(info))),
+                    .setContent(asJson(adaptedRequest))),
             "Unable to create container: ",
             info);