Draft — deliberately. This cannot be merged until docker-java ships a release containing the
wslc:// transport. Raised now so the Testcontainers-side design can be reviewed in parallel rather
than after the fact, and so the ordering between the two projects is visible.

Closes #11987 once the dependency below lands.

Why

WSL 2.9+ ships Microsoft's own container runtime, driven by the wslc CLI. It runs dockerd in a
lightweight VM and publishes no Windows named pipe and no TCP port — the only host-visible
channel is a stdio bridge, wslc system session run docker system dial-stdio. None of the existing
strategies can find an endpoint there, so Testcontainers fails with
Could not find a valid Docker environment on a machine that has a perfectly good daemon.

What this adds

• WslcSocketClientProviderStrategy — resolves to wslc://localhost on Windows when the wslc
  CLI is present.
• one line in the SPI registration (META-INF/services/…DockerClientProviderStrategy).
• two wslc cases in DockerClientProviderStrategy — in test() and in
  resolveDockerHostIpAddress(), see below.
• WslcSocketClientProviderStrategyTest — 18 tests, no Docker required.
• a TODO in core/build.gradle marking the coordinates to bump once docker-java releases.

The strategy is modelled closely on NpipeSocketClientProviderStrategy: same final class, same
@Deprecated-for-SPI javadoc, same public static final int PRIORITY expressed relative to a
neighbour, same four overrides.

Nothing changes for existing users

public static final int PRIORITY = NpipeSocketClientProviderStrategy.PRIORITY - 10;

Priority sits below the named-pipe strategy, so a Docker Desktop or Podman pipe always wins.
wslc is reached only when that pipe is absent, and only on Windows.

The strategy also overrides isPersistable() to return false. A remembered strategy is loaded
ahead of the priority-sorted ones by getFirstValidStrategy, so persisting this one would let wslc
keep winning on later runs even once a named pipe became available — quietly defeating the priority
above.

Discovery is also lazy: getFirstValidStrategy filters a Stream terminated by findFirst(), so on
a machine where the named pipe works, isApplicable() is never called here and no process is
spawned. The probe costs something only on machines that would otherwise have failed outright.

Detection is a probe, not a guess

protected boolean isApplicable() {
    return applies(SystemUtils.IS_OS_WINDOWS);
}

The probe runs wslc version — metadata only, and unlike most subcommands it does not start the
container VM — and requires exit code 0. If wslc is absent, ProcessBuilder.start() fails
immediately. The executable is overridable with WSLC_EXECUTABLE (a blank value is treated as
unset), the process is bounded by a timeout and reaped in a finally, both streams are merged and
discarded so the child can never block on an undrained pipe, and an interrupt restores the interrupt
flag rather than swallowing it. Every declining path logs at debug, so a half-installed wslc does
not fail silently.

Redirect.DISCARD would express the discard more directly but is Java 9+, and core main sources
compile at release 8; the null device is selected per platform rather than hardcoding Windows'
NUL.

Why test() needed a case too

DockerClientProviderStrategy.test() switches on the scheme, and its default branch logs
Unknown DOCKER_HOST scheme {}, skipping the strategy test... at warn. Without a wslc case,
every user of this feature would see that warning on every startup, for a scheme Testcontainers now
supports. The added case skips the socket probe deliberately and says so at debug:

case "wslc":
    // wslc publishes neither a socket file nor a port: the daemon is reached over a
    // stdio bridge, so there is nothing here to connect() to. Reachability is
    // established by the infoCmd() ping in tryOutStrategy instead.
    log.debug("wslc transport has no connectable endpoint, deferring to the daemon ping");
    return true;

Reachability is still verified — tryOutStrategy runs infoCmd().exec() immediately afterwards and
falls through to the next strategy if it throws.

resolveDockerHostIpAddress() needed the same treatment, and for a more visible reason: its default
branch returns null, which would leave ContainerState.getHost() with no address for every wslc
user. It now returns localhost, since the wslc control plane relays published container ports onto
127.0.0.1 on the Windows host.

Testing

WslcSocketClientProviderStrategyTest — 18 tests, no Docker and no wslc needed. The probe was
split into applies(boolean), resolveExecutable(String), probeCommand(String, boolean) and
probe(ProcessBuilder, long) so each is reachable from any platform; the Windows gate cannot
otherwise be varied at runtime.

Covered: both sides of the Windows gate; all three resolveExecutable cases including blank; both
platforms' null device; and all five outcomes of probe — exit 0, non-zero exit, timeout,
unrunnable executable, and interruption with the flag restored. isPersistable() and the new
test() case are covered too, and resolveDockerHostIpAddress() gains a wslc case alongside its
sibling schemes in DockerClientConfigUtilsTest. Processes are driven through the JVM running the
build, so the tests are platform-neutral.

One test is assumeThat-guarded to off-Windows only (asserting the strategy declines there), so 18
run on CI and 17 on a Windows workstation.

Verified by hand on Windows 11 / WSL 2.9.4 against a locally built docker-java carrying the wslc://
transport: with no DOCKER_HOST set and no Docker Desktop or Podman pipe present, Testcontainers
resolves the wslc strategy and containers start, stop and expose ports normally.

Build checks

Run against this branch on current main:

:testcontainers:compileJava      SUCCESS
:testcontainers:checkstyleMain   SUCCESS
:testcontainers:spotlessCheck    SUCCESS
:testcontainers:test  (new test) 18 passed, 1 skipped (Windows workstation), 0 failed

The strategy compiles and passes every check against the released docker-java (3.7.1, as
core/build.gradle pins today) — it only constructs a URI, so nothing here needs the wslc://
transport at compile time. The only core/build.gradle change is a comment. On Linux CI
isApplicable() short-circuits on the OS check, so the rest of the suite is unaffected.

Before merge

• docker-java releases a version containing the wslc:// transport
  (Feature: add a wslc:// transport for WSL Containers (Microsoft WSL 2.9+) docker-java/docker-java#2658, implemented in feat(wslc): add WSL Containers (wslc://) transport, lifecycle integra… docker-java/docker-java#2659)
• bump the docker-java-bom platform in core/build.gradle to that release — a TODO(wslc)
  comment sits directly above both coordinates
• documentation, if core transport strategies are documented anywhere I have missed

Open questions

1. Is a strategy the right home for this, or would you rather wslc be reached only by an
   explicit DOCKER_HOST=wslc://localhost? Auto-detection is what makes it work out of the box, and
   the lazy discovery above means it costs nothing when another endpoint is available. I can gate it
   behind an opt-in property instead if you prefer a more conservative default.
2. Priority gap of 10 — chosen to sit clear of the named-pipe strategy without colliding with
   RootlessDockerClientProviderStrategy or DockerDesktopClientProviderStrategy. Say if you would
   rather it sat elsewhere in the order.
3. Probe timeout — currently 10s, generous for a cold wslc.exe, and only ever paid on the
   fallback path. Lower if you would rather fail fast.

Summary by CodeRabbit

• New Features

  • Added Windows support for connecting to Docker through the WSL Containers daemon.
  • Automatically detects and validates the wslc command-line tool.
  • Keeps Docker Desktop as the preferred connection method when available.

• Bug Fixes

  • Improved handling of wslc:// Docker hosts.
  • Correctly resolves container host addresses to localhost.
  • Added clearer handling for unavailable, interrupted, or timed-out daemon checks.