[grid] Improve Docker client for Dynamic Grid

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

@@ -37,7 +37,7 @@ public Docker(HttpHandler client) {
    * 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
+   * @param apiVersion Optional API version to use (e.g., "1.40" or "1.44"). If null, the version
    *     will be auto-detected.
    */
   public Docker(HttpHandler client, String apiVersion) {

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

@@ -39,13 +39,14 @@ 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
+  // 1.48 is for Docker Engine v28+ with multi-platform and gateway priority support
+  // 1.44 is for Docker Engine v25+ with multi-network and modern features
+  // 1.40 is maintained for backward compatibility with legacy engines (Docker v19.03+)
+  // All use the same generic implementation with version-specific adapters
   private static final Map<Version, Function<HttpHandler, DockerProtocol>> SUPPORTED_VERSIONS =
       ImmutableMap.of(
+          new Version("1.48"), client -> new DockerClient(client, "1.48"),
           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;
@@ -56,10 +57,10 @@ public VersionCommand(HttpHandler 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
+   * override the automatic version detection and force a specific API version (e.g., 1.40 for
    * legacy Docker engines).
    *
-   * @param requestedVersion The API version to use (e.g., "1.41" or "1.44")
+   * @param requestedVersion The API version to use (e.g., "1.40" or "1.44")
    * @return Optional containing the DockerProtocol implementation if the version is supported
    */
   public Optional<DockerProtocol> getDockerProtocol(String requestedVersion) {

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

@@ -26,11 +26,12 @@
  *
  * <ul>
  *   <li>API v1.40-1.43: Uses {@link V140Adapter}
- *   <li>API v1.44+: Uses {@link V144Adapter}
+ *   <li>API v1.44-1.47: Uses {@link V144Adapter}
+ *   <li>API v1.48+: Uses {@link V148Adapter}
  * </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.
+ * API versions automatically use the most appropriate adapter.
  */
 class AdapterFactory {
 
@@ -39,7 +40,7 @@ class AdapterFactory {
   /**
    * Creates an appropriate adapter for the given API version.
    *
-   * @param apiVersion The Docker API version (e.g., "1.40", "1.44")
+   * @param apiVersion The Docker API version (e.g., "1.40", "1.44", "1.48")
    * @return An adapter suitable for the specified API version
    * @throws IllegalArgumentException if apiVersion is null or empty
    */
@@ -48,7 +49,13 @@ public static ApiVersionAdapter createAdapter(String apiVersion) {
       throw new IllegalArgumentException("API version cannot be null or empty");
     }
 
-    // API v1.44+ uses the new adapter
+    // API v1.48+ uses the latest adapter with multi-platform and gateway priority support
+    if (compareVersions(apiVersion, "1.48") >= 0) {
+      LOG.fine("Using V148Adapter for API version " + apiVersion);
+      return new V148Adapter(apiVersion);
+    }
+
+    // API v1.44-1.47 uses the v1.44 adapter
     if (compareVersions(apiVersion, "1.44") >= 0) {
       LOG.fine("Using V144Adapter for API version " + apiVersion);
       return new V144Adapter(apiVersion);

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

@@ -17,7 +17,6 @@
 
 package org.openqa.selenium.docker.client;
 
-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;
@@ -48,14 +47,6 @@ class CreateContainer {
   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);

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

@@ -34,7 +34,6 @@
 
 public class DockerClient implements DockerProtocol {
 
-  static final String DOCKER_API_VERSION = "1.41";
   private static final Logger LOG = Logger.getLogger(DockerClient.class.getName());
   private final String apiVersion;
   private final ApiVersionAdapter adapter;
@@ -47,10 +46,6 @@ public class DockerClient implements DockerProtocol {
   private final InspectContainer inspectContainer;
   private final GetContainerLogs containerLogs;
 
-  public DockerClient(HttpHandler client) {
-    this(client, DOCKER_API_VERSION);
-  }
-
   public DockerClient(HttpHandler client, String apiVersion) {
     Require.nonNull("HTTP client", client);
     this.apiVersion = Require.nonNull("API version", apiVersion);

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

@@ -18,7 +18,6 @@
 package org.openqa.selenium.docker.client;
 
 import static java.net.HttpURLConnection.HTTP_OK;
-import static org.openqa.selenium.docker.client.DockerClient.DOCKER_API_VERSION;
 import static org.openqa.selenium.remote.http.HttpMethod.GET;
 
 import java.util.Arrays;
@@ -38,10 +37,6 @@ class GetContainerLogs {
   private final HttpHandler client;
   private final String apiVersion;
 
-  public GetContainerLogs(HttpHandler client) {
-    this(client, DOCKER_API_VERSION);
-  }
-
   public GetContainerLogs(HttpHandler client, String apiVersion) {
     this.client = Require.nonNull("HTTP client", client);
     this.apiVersion = Require.nonNull("API version", apiVersion);

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

@@ -18,7 +18,6 @@
 package org.openqa.selenium.docker.client;
 
 import static java.net.HttpURLConnection.HTTP_OK;
-import static org.openqa.selenium.docker.client.DockerClient.DOCKER_API_VERSION;
 import static org.openqa.selenium.json.Json.MAP_TYPE;
 import static org.openqa.selenium.remote.http.HttpMethod.GET;
 
@@ -44,10 +43,6 @@ class InspectContainer {
   private final String apiVersion;
   private final ApiVersionAdapter adapter;
 
-  public InspectContainer(HttpHandler client) {
-    this(client, DOCKER_API_VERSION, AdapterFactory.createAdapter(DOCKER_API_VERSION));
-  }
-
   public InspectContainer(HttpHandler client, String apiVersion) {
     this(client, apiVersion, AdapterFactory.createAdapter(apiVersion));
   }

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

@@ -17,7 +17,6 @@
 
 package org.openqa.selenium.docker.client;
 
-import static org.openqa.selenium.docker.client.DockerClient.DOCKER_API_VERSION;
 import static org.openqa.selenium.remote.http.HttpMethod.GET;
 
 import org.openqa.selenium.docker.ContainerId;
@@ -30,10 +29,6 @@ class IsContainerPresent {
   private final HttpHandler client;
   private final String apiVersion;
 
-  public IsContainerPresent(HttpHandler client) {
-    this(client, DOCKER_API_VERSION);
-  }
-
   public IsContainerPresent(HttpHandler client, String apiVersion) {
     this.client = Require.nonNull("Http client", client);
     this.apiVersion = Require.nonNull("API version", apiVersion);

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

@@ -18,7 +18,6 @@
 package org.openqa.selenium.docker.client;
 
 import static com.google.common.collect.ImmutableSet.toImmutableSet;
-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.remote.http.Contents.string;
 import static org.openqa.selenium.remote.http.HttpMethod.GET;
@@ -47,10 +46,6 @@ class ListImages {
   private final String apiVersion;
   private final ApiVersionAdapter adapter;
 
-  public ListImages(HttpHandler client) {
-    this(client, DOCKER_API_VERSION, AdapterFactory.createAdapter(DOCKER_API_VERSION));
-  }
-
   public ListImages(HttpHandler client, String apiVersion) {
     this(client, apiVersion, AdapterFactory.createAdapter(apiVersion));
   }
@@ -67,7 +62,7 @@ public Set<Image> apply(Reference reference) {
     String familiarName = reference.getFamiliarName();
     Map<String, Object> filters = ImmutableMap.of("reference", ImmutableMap.of(familiarName, true));
 
-    // https://docs.docker.com/engine/api/v1.41/#operation/ImageList
+    // https://docs.docker.com/engine/api/v1.40/#operation/ImageList
     HttpRequest req =
         new HttpRequest(GET, String.format("/v%s/images/json", apiVersion))
             .addHeader("Content-Type", JSON_UTF_8)

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

@@ -17,7 +17,6 @@
 
 package org.openqa.selenium.docker.client;
 
-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.HttpMethod.POST;
@@ -39,10 +38,6 @@ class PullImage {
   private final HttpHandler client;
   private final String apiVersion;
 
-  public PullImage(HttpHandler client) {
-    this(client, DOCKER_API_VERSION);
-  }
-
   public PullImage(HttpHandler client, String apiVersion) {
     this.client = Require.nonNull("HTTP client", client);
     this.apiVersion = Require.nonNull("API version", apiVersion);

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

@@ -17,7 +17,6 @@
 
 package org.openqa.selenium.docker.client;
 
-import static org.openqa.selenium.docker.client.DockerClient.DOCKER_API_VERSION;
 import static org.openqa.selenium.docker.client.DockerMessages.throwIfNecessary;
 import static org.openqa.selenium.remote.http.HttpMethod.POST;
 
@@ -30,10 +29,6 @@ class StartContainer {
   private final HttpHandler client;
   private final String apiVersion;
 
-  public StartContainer(HttpHandler client) {
-    this(client, DOCKER_API_VERSION);
-  }
-
   public StartContainer(HttpHandler client, String apiVersion) {
     this.client = Require.nonNull("HTTP client", client);
     this.apiVersion = Require.nonNull("API version", apiVersion);

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

@@ -17,7 +17,6 @@
 
 package org.openqa.selenium.docker.client;
 
-import static org.openqa.selenium.docker.client.DockerClient.DOCKER_API_VERSION;
 import static org.openqa.selenium.docker.client.DockerMessages.throwIfNecessary;
 import static org.openqa.selenium.remote.http.HttpMethod.POST;
 
@@ -31,10 +30,6 @@ class StopContainer {
   private final HttpHandler client;
   private final String apiVersion;
 
-  public StopContainer(HttpHandler client) {
-    this(client, DOCKER_API_VERSION);
-  }
-
   public StopContainer(HttpHandler client, String apiVersion) {
     this.client = Require.nonNull("HTTP client", client);
     this.apiVersion = Require.nonNull("API version", apiVersion);

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

@@ -29,7 +29,7 @@
  * <ul>
  *   <li>Use {@code VirtualSize} field in image responses
  *   <li>Support single network endpoint in container creation
- *   <li>Use {@code filter} parameter (deprecated in 1.41+, use {@code filters})
+ *   <li>Use {@code filter} parameter (deprecated in 1.40+, use {@code filters})
  * </ul>
  *
  * <p>This adapter normalizes responses to ensure compatibility with newer code that expects the

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

@@ -115,9 +115,14 @@ public Map<String, Object> adaptContainerInspectResponse(Map<String, Object> res
     // v1.44+ includes DNSNames field
     // Ensure deprecated fields are handled if present
     @SuppressWarnings("unchecked")
-    Map<String, Object> networkSettings = (Map<String, Object>) adapted.get("NetworkSettings");
+    Map<String, Object> originalNetworkSettings =
+        (Map<String, Object>) adapted.get("NetworkSettings");
+
+    if (originalNetworkSettings != null) {
+      // Create defensive copy to avoid mutating the original response
+      Map<String, Object> networkSettings = new HashMap<>(originalNetworkSettings);
+      adapted.put("NetworkSettings", networkSettings);
 
-    if (networkSettings != null) {
       // Remove deprecated fields if present (they shouldn't be in v1.44+)
       String[] deprecatedFields = {
         "HairpinMode",