> getHeaders() {
+ return Collections.singletonMap("Content-Type", Collections.singletonList("application/json"));
+ }
+ @Override public InputStream getBody() {
+ return new ByteArrayInputStream(bytes);
+ }
+ @Override public void close() {
+ }
+ };
+ }
+
+ @Override
+ public void close() throws IOException {
+ delegate.close();
+ }
+}
diff --git a/docker-java-transport-httpclient5/src/main/java/com/github/dockerjava/httpclient5/ApacheDockerHttpClientImpl.java b/docker-java-transport-httpclient5/src/main/java/com/github/dockerjava/httpclient5/ApacheDockerHttpClientImpl.java
index c97a2bc45..8de5e6686 100644
--- a/docker-java-transport-httpclient5/src/main/java/com/github/dockerjava/httpclient5/ApacheDockerHttpClientImpl.java
+++ b/docker-java-transport-httpclient5/src/main/java/com/github/dockerjava/httpclient5/ApacheDockerHttpClientImpl.java
@@ -4,6 +4,7 @@
import com.github.dockerjava.transport.NamedPipeSocket;
import com.github.dockerjava.transport.SSLConfig;
import com.github.dockerjava.transport.UnixSocket;
+import com.github.dockerjava.transport.WslcSocket;
import org.apache.hc.client5.http.SystemDefaultDnsResolver;
import org.apache.hc.client5.http.classic.methods.HttpUriRequestBase;
@@ -74,6 +75,7 @@ protected ApacheDockerHttpClientImpl(
switch (dockerHost.getScheme()) {
case "unix":
case "npipe":
+ case "wslc":
pathPrefix = "";
host = new HttpHost(dockerHost.getScheme(), "localhost", 2375);
break;
@@ -151,6 +153,8 @@ private HttpClientConnectionOperator createConnectionOperator(
return UnixSocket.get(dockerHostPath);
} else if ("npipe".equalsIgnoreCase(dockerHostScheme)) {
return new NamedPipeSocket(dockerHostPath);
+ } else if ("wslc".equalsIgnoreCase(dockerHostScheme)) {
+ return new WslcSocket(dockerHostPath);
} else {
return socksProxy == null ? new Socket() : new Socket(socksProxy);
}
diff --git a/docker-java-transport/src/main/java/com/github/dockerjava/transport/WslcSocket.java b/docker-java-transport/src/main/java/com/github/dockerjava/transport/WslcSocket.java
new file mode 100644
index 000000000..9fbd86a51
--- /dev/null
+++ b/docker-java-transport/src/main/java/com/github/dockerjava/transport/WslcSocket.java
@@ -0,0 +1,119 @@
+package com.github.dockerjava.transport;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.net.Socket;
+import java.net.SocketAddress;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+/**
+ * A {@link Socket} whose streams are backed by a child process that bridges stdin/stdout to the
+ * Docker daemon socket inside a WSL Containers (wslc) virtual machine, via
+ * {@code wslc system session run docker system dial-stdio}.
+ *
+ * wslc exposes neither a Windows named pipe nor a TCP port on the host, so this stdio bridge (the
+ * same mechanism used by {@code DOCKER_HOST=ssh://}) is the only host-visible channel to the daemon.
+ * Supplying a {@link Socket} is sufficient: Apache HttpClient5 — including the hijacked
+ * exec/attach/log streams — drives it like any other socket.
+ *
+ * The executable is taken from the {@code wslc://} URL path if present (e.g. {@code wslc:///wslc.exe}),
+ * otherwise from the {@code WSLC_EXECUTABLE} environment variable, otherwise {@code wslc.exe}.
+ */
+public class WslcSocket extends Socket {
+
+ // java.util.logging keeps this transport module dependency-free (it uses no slf4j).
+ private static final Logger LOGGER = Logger.getLogger(WslcSocket.class.getName());
+
+ private final String executable;
+
+ private volatile Process process;
+
+ public WslcSocket(String dockerHostPath) {
+ this.executable = resolveExecutable(dockerHostPath);
+ }
+
+ static String resolveExecutable(String dockerHostPath) {
+ if (dockerHostPath == null || dockerHostPath.trim().isEmpty() || "/".equals(dockerHostPath)) {
+ String fromEnv = System.getenv("WSLC_EXECUTABLE");
+ return fromEnv != null && !fromEnv.trim().isEmpty() ? fromEnv : "wslc.exe";
+ }
+ // A leading slash comes from a URL like wslc:///wslc.exe -- strip it for the executable name.
+ return dockerHostPath.startsWith("/") ? dockerHostPath.substring(1) : dockerHostPath;
+ }
+
+ @Override
+ public void connect(SocketAddress endpoint) throws IOException {
+ connect(endpoint, 0);
+ }
+
+ @Override
+ public void connect(SocketAddress endpoint, int timeout) throws IOException {
+ // The connect timeout is not applied to the bridge spawn: ProcessBuilder.start() returns
+ // immediately and the daemon stream has no socket-level read timeout (see class javadoc).
+ List command = new ArrayList<>();
+ command.add(executable);
+ command.add("system");
+ command.add("session");
+ command.add("run");
+ command.add("docker");
+ command.add("system");
+ command.add("dial-stdio");
+
+ ProcessBuilder processBuilder = new ProcessBuilder(command);
+ processBuilder.redirectErrorStream(false);
+ try {
+ process = processBuilder.start();
+ } catch (IOException e) {
+ throw new IOException("Failed to start wslc Docker bridge " + command + ": " + e.getMessage(), e);
+ }
+
+ // Drain the bridge's stderr so a full pipe buffer can never block the daemon stream, and log
+ // it at FINE so connection failures (e.g. dial-stdio cannot reach the daemon) are diagnosable.
+ final Process startedProcess = process;
+ Thread stderrDrain = new Thread(() -> {
+ byte[] buffer = new byte[1024];
+ try (InputStream stderr = startedProcess.getErrorStream()) {
+ int read;
+ while ((read = stderr.read(buffer)) != -1) {
+ if (read > 0 && LOGGER.isLoggable(Level.FINE)) {
+ LOGGER.fine("wslc bridge stderr: " + new String(buffer, 0, read, StandardCharsets.UTF_8).trim());
+ }
+ }
+ } catch (IOException ignored) {
+ // process gone
+ }
+ }, "wslc-bridge-stderr");
+ stderrDrain.setDaemon(true);
+ stderrDrain.start();
+ }
+
+ @Override
+ public InputStream getInputStream() throws IOException {
+ if (process == null) {
+ throw new IOException("Socket is not connected");
+ }
+ // stdout of the bridge process = bytes coming back from the Docker daemon socket
+ return process.getInputStream();
+ }
+
+ @Override
+ public OutputStream getOutputStream() throws IOException {
+ if (process == null) {
+ throw new IOException("Socket is not connected");
+ }
+ // stdin of the bridge process = bytes written to the Docker daemon socket
+ return process.getOutputStream();
+ }
+
+ @Override
+ public void close() throws IOException {
+ if (process != null) {
+ process.destroyForcibly();
+ }
+ }
+}
diff --git a/docker-java/src/test/java/com/github/dockerjava/core/WslcLifecycleDockerHttpClientTest.java b/docker-java/src/test/java/com/github/dockerjava/core/WslcLifecycleDockerHttpClientTest.java
new file mode 100644
index 000000000..3d2eb0497
--- /dev/null
+++ b/docker-java/src/test/java/com/github/dockerjava/core/WslcLifecycleDockerHttpClientTest.java
@@ -0,0 +1,129 @@
+package com.github.dockerjava.core;
+
+import com.github.dockerjava.transport.DockerHttpClient;
+import org.junit.Test;
+
+import java.io.ByteArrayInputStream;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicReference;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertTrue;
+
+/**
+ * Unit tests for {@link WslcLifecycleDockerHttpClient} that exercise its request routing and
+ * fallback behaviour without a real daemon or a real {@code wslc} CLI. Lifecycle calls are forced
+ * to fail deterministically by pointing the decorator at a non-existent executable, which is enough
+ * to assert that non-lifecycle traffic is delegated untouched and that failures degrade gracefully.
+ */
+public class WslcLifecycleDockerHttpClientTest {
+
+ private static final String MISSING_WSLC = "no-such-wslc-binary-xyz";
+
+ /** A recording delegate that returns a fixed response and captures the last request it saw. */
+ private static final class RecordingDelegate implements DockerHttpClient {
+ final AtomicReference last = new AtomicReference<>();
+ private final int status;
+ private final byte[] body;
+
+ RecordingDelegate(int status, String body) {
+ this.status = status;
+ this.body = body.getBytes(StandardCharsets.UTF_8);
+ }
+
+ @Override
+ public Response execute(Request request) {
+ last.set(request);
+ return new Response() {
+ @Override public int getStatusCode() {
+ return status;
+ }
+ @Override public Map> getHeaders() {
+ return Collections.emptyMap();
+ }
+ @Override public InputStream getBody() {
+ return new ByteArrayInputStream(body);
+ }
+ @Override public void close() {
+ }
+ };
+ }
+
+ @Override
+ public void close() {
+ }
+ }
+
+ private static String read(DockerHttpClient.Response response) throws Exception {
+ try (InputStream in = response.getBody()) {
+ java.io.ByteArrayOutputStream bos = new java.io.ByteArrayOutputStream();
+ byte[] buf = new byte[1024];
+ int n;
+ while ((n = in.read(buf)) != -1) {
+ bos.write(buf, 0, n);
+ }
+ return new String(bos.toByteArray(), StandardCharsets.UTF_8);
+ }
+ }
+
+ @Test
+ public void nonLifecycleRequestIsDelegatedUnchanged() throws Exception {
+ RecordingDelegate delegate = new RecordingDelegate(200, "[{\"Id\":\"img\"}]");
+ WslcLifecycleDockerHttpClient client = new WslcLifecycleDockerHttpClient(delegate, MISSING_WSLC);
+
+ DockerHttpClient.Request req = DockerHttpClient.Request.builder()
+ .method(DockerHttpClient.Request.Method.GET)
+ .path("/images/json")
+ .headers(Collections.emptyMap())
+ .build();
+ DockerHttpClient.Response resp = client.execute(req);
+
+ assertEquals(200, resp.getStatusCode());
+ assertEquals("[{\"Id\":\"img\"}]", read(resp));
+ assertNotNull("delegate should have been invoked", delegate.last.get());
+ assertEquals("/images/json", delegate.last.get().path());
+ }
+
+ @Test
+ public void inspectFallsBackToDaemonBodyWhenWslcUnavailable() throws Exception {
+ String inspect = "{\"Id\":\"abc123\",\"NetworkSettings\":{\"Ports\":{}}}";
+ RecordingDelegate delegate = new RecordingDelegate(200, inspect);
+ WslcLifecycleDockerHttpClient client = new WslcLifecycleDockerHttpClient(delegate, MISSING_WSLC);
+
+ DockerHttpClient.Request req = DockerHttpClient.Request.builder()
+ .method(DockerHttpClient.Request.Method.GET)
+ .path("/containers/abc123/json")
+ .headers(Collections.emptyMap())
+ .build();
+ DockerHttpClient.Response resp = client.execute(req);
+
+ // wslc list cannot run, so the port override is skipped and the daemon's body is returned as-is.
+ assertEquals(200, resp.getStatusCode());
+ assertEquals(inspect, read(resp));
+ }
+
+ @Test
+ public void createReturns500WhenWslcCannotRun() throws Exception {
+ RecordingDelegate delegate = new RecordingDelegate(201, "{}");
+ WslcLifecycleDockerHttpClient client = new WslcLifecycleDockerHttpClient(delegate, MISSING_WSLC);
+
+ DockerHttpClient.Request req = DockerHttpClient.Request.builder()
+ .method(DockerHttpClient.Request.Method.POST)
+ .path("/containers/create?name=demo")
+ .headers(Collections.emptyMap())
+ .bodyBytes("{\"Image\":\"busybox\"}".getBytes(StandardCharsets.UTF_8))
+ .build();
+ DockerHttpClient.Response resp = client.execute(req);
+
+ // The create is routed to `wslc create`; with no wslc on PATH it fails and surfaces as a 500,
+ // and it must NOT have been forwarded to the daemon delegate.
+ assertEquals(500, resp.getStatusCode());
+ assertTrue(read(resp).contains("wslc create failed"));
+ assertEquals("delegate must not receive the create", null, delegate.last.get());
+ }
+}
diff --git a/docker-java/src/test/java/com/github/dockerjava/transport/WslcSocketTest.java b/docker-java/src/test/java/com/github/dockerjava/transport/WslcSocketTest.java
new file mode 100644
index 000000000..0d2b02d53
--- /dev/null
+++ b/docker-java/src/test/java/com/github/dockerjava/transport/WslcSocketTest.java
@@ -0,0 +1,50 @@
+package com.github.dockerjava.transport;
+
+import org.junit.Test;
+
+import java.io.IOException;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.fail;
+
+public class WslcSocketTest {
+
+ @Test
+ public void resolveExecutableDefaultsConsistentlyForEmptyOrRootPath() {
+ // wslc:// -> null/empty path, wslc:/// -> "/" path: all resolve identically (to WSLC_EXECUTABLE
+ // if set, otherwise "wslc.exe"). Assert consistency unconditionally and the default only when
+ // the environment does not override it, so the test does not depend on WSLC_EXECUTABLE.
+ String fromNull = WslcSocket.resolveExecutable(null);
+ assertEquals(fromNull, WslcSocket.resolveExecutable(""));
+ assertEquals(fromNull, WslcSocket.resolveExecutable("/"));
+ if (System.getenv("WSLC_EXECUTABLE") == null) {
+ assertEquals("wslc.exe", fromNull);
+ }
+ }
+
+ @Test
+ public void resolveExecutableStripsLeadingSlashFromUrlPath() {
+ // wslc:///wslc.exe -> path "/wslc.exe"
+ assertEquals("wslc.exe", WslcSocket.resolveExecutable("/wslc.exe"));
+ }
+
+ @Test
+ public void resolveExecutableKeepsAbsoluteWindowsPath() {
+ assertEquals("C:\\Program Files\\WSL\\wslc.exe",
+ WslcSocket.resolveExecutable("C:\\Program Files\\WSL\\wslc.exe"));
+ }
+
+ @Test
+ public void connectWithMissingExecutableThrowsIoException() throws Exception {
+ WslcSocket socket = new WslcSocket("no-such-wslc-binary-xyz");
+ try {
+ socket.connect(null, 0);
+ fail("expected IOException for a missing bridge executable");
+ } catch (IOException e) {
+ assertTrue(e.getMessage(), e.getMessage().contains("no-such-wslc-binary-xyz"));
+ } finally {
+ socket.close();
+ }
+ }
+}