diff --git a/.github/workflows/pr-ci.yml b/.github/workflows/pr-ci.yml index 1a289c1290..74126c377c 100644 --- a/.github/workflows/pr-ci.yml +++ b/.github/workflows/pr-ci.yml @@ -768,6 +768,42 @@ jobs: --distribution Ubuntu-24.04 --timeout 4m --state-file "$env:RUNNER_TEMP\devsy-ci\docker-wsl-state.json" + # The WSLg specs and the parity probe need Compose on the Windows side. + # The fixture exports DOCKER_CONFIG, which holds the plugin. + - name: install pinned Windows Compose plugin + if: matrix.setup_docker_wsl + shell: pwsh + run: | + if ([string]::IsNullOrEmpty($env:DOCKER_CONFIG)) { throw 'WSL fixture Docker config is missing' } + $pluginDir = Join-Path $env:DOCKER_CONFIG 'cli-plugins' + New-Item -ItemType Directory -Force $pluginDir | Out-Null + $plugin = Join-Path $pluginDir 'docker-compose.exe' + Invoke-WebRequest ` + -Uri 'https://github.com/docker/compose/releases/download/v5.6.0/docker-compose-windows-x86_64.exe' ` + -OutFile $plugin + $expectedHash = '8aeaa0055e660e12cf07cd70680dc8333957fe6718528b91ec3da084eab62483' + $actualHash = (Get-FileHash -Path $plugin -Algorithm SHA256).Hash.ToLower() + if ($actualHash -ne $expectedHash) { throw 'Compose SHA256 mismatch' } + + - name: setup Go + if: matrix.setup_docker_wsl + uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7 + with: + go-version-file: go.mod + + - name: test real noninteractive WSLg discovery and Compose parity + if: matrix.setup_docker_wsl + shell: pwsh + timeout-minutes: 8 + env: + DEVSY_WSLG_TEST_DISTRO: Ubuntu-24.04 + DEVSY_WSLG_TEST_USER: devsyci + run: | + docker compose version + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + go test -count=1 -v -timeout 3m ./pkg/wslg ./pkg/compose -run '^TestWSLg' + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + # Runs the suite's `host_setup` actions from hack/ci/suites.yaml # (for example removing Docker or trusting a local registry). - name: host setup diff --git a/cmd/workspace/up/secrets_preflight.go b/cmd/workspace/up/secrets_preflight.go index 347e330c13..b65ef4359b 100644 --- a/cmd/workspace/up/secrets_preflight.go +++ b/cmd/workspace/up/secrets_preflight.go @@ -43,6 +43,9 @@ func (e *unavailableValuesError) Unwrap() []error { return e.causes } // Preflight locally known requirements before workspace resolution can create // remote resources. Project SOPS sources remain on the later discovery path. func (cmd *UpCmd) preflightLocalValues(cfg *config.Config) error { + if err := cmd.preflightWSLgContext(cfg); err != nil { + return err + } refs, err := cmd.localPreflightRefs(cfg) if err != nil { return err diff --git a/cmd/workspace/up/up_client.go b/cmd/workspace/up/up_client.go index 817c6827e7..b3b5dff2eb 100644 --- a/cmd/workspace/up/up_client.go +++ b/cmd/workspace/up/up_client.go @@ -138,6 +138,9 @@ func (cmd *UpCmd) postResolveWorkspace( } return err } + if err := cmd.preflightWSLgClient(devsyConfig, client); err != nil { + return cleanupOnFailure(err) + } if err := cmd.prepareResolvedWorkspaceSecrets(ctx, devsyConfig, client); err != nil { return cleanupOnFailure(err) } diff --git a/cmd/workspace/up/wslg.go b/cmd/workspace/up/wslg.go new file mode 100644 index 0000000000..c19468dd07 --- /dev/null +++ b/cmd/workspace/up/wslg.go @@ -0,0 +1,80 @@ +package up + +import ( + "os" + "runtime" + + client2 "github.com/devsy-org/devsy/pkg/client" + "github.com/devsy-org/devsy/pkg/config" + "github.com/devsy-org/devsy/pkg/docker" + "github.com/devsy-org/devsy/pkg/provider" + "github.com/devsy-org/devsy/pkg/wslg" +) + +const wslgGoosWindows = "windows" + +func (cmd *UpCmd) preflightWSLgContext(cfg *config.Config) error { + if !cfg.ContextOptionBool(config.ContextOptionWSLgEnabled) { + return nil + } + if runtime.GOOS != wslgGoosWindows || cmd.Platform.Enabled { + return wslg.ErrUnsupported + } + return wslg.ValidateTarget( + wslg.Target{ + Distro: cfg.ContextOption(config.ContextOptionWSLgDistro), + User: cfg.ContextOption(config.ContextOptionWSLgUser), + }, + ) +} + +// Reject unsupported providers before Create/Start can provision a machine. +// The runner subsequently checks its actual driver before discovering values. +func (cmd *UpCmd) preflightWSLgClient( + cfg *config.Config, + client client2.BaseWorkspaceClient, +) error { + if !cfg.ContextOptionBool(config.ContextOptionWSLgEnabled) { + return nil + } + local, ok := client.(client2.WorkspaceClient) + if !ok || !local.AgentLocal() { + return wslg.ErrUnsupported + } + _, info, err := local.AgentInfo(cmd.CLIOptions) + if err != nil { + return err + } + if err := wslg.CheckEnvironmentSources(map[string][]string{ + "process environment": os.Environ(), + "--init-env": cmd.InitEnv, + "provider Docker environment": wslg.Pairs(info.Agent.Docker.Env), + }, runtime.GOOS == wslgGoosWindows); err != nil { + return err + } + return validateWSLgAgent(info.Agent) +} + +func validateWSLgAgent(agent provider.ProviderAgentConfig) error { + if agent.Driver != "" && agent.Driver != provider.DockerDriver { + return wslg.ErrUnsupported + } + var containerRuntime docker.ContainerRuntime + if agent.Docker.Runtime != "" { + var err error + containerRuntime, err = docker.RuntimeFromName(agent.Docker.Runtime) + if err != nil { + return err + } + } else { + command := agent.Docker.Path + if command == "" { + command = provider.DockerDriver + } + containerRuntime = docker.DetectRuntime(command) + } + if containerRuntime.Name() != docker.RuntimeDocker { + return wslg.ErrUnsupported + } + return nil +} diff --git a/cmd/workspace/up/wslg_test.go b/cmd/workspace/up/wslg_test.go new file mode 100644 index 0000000000..2ff7781450 --- /dev/null +++ b/cmd/workspace/up/wslg_test.go @@ -0,0 +1,62 @@ +package up + +import ( + "context" + "runtime" + "testing" + + "github.com/devsy-org/devsy/pkg/config" + "github.com/devsy-org/devsy/pkg/provider" + "github.com/devsy-org/devsy/pkg/wslg" + "github.com/stretchr/testify/require" +) + +func TestWSLgPreflightBeforeWorkspaceProvisioning(t *testing.T) { + cfg := testConfig() + cmd := &UpCmd{} + require.NoError(t, cmd.preflightWSLgContext(cfg)) + cfg.Current().Options = map[string]config.OptionValue{ + config.ContextOptionWSLgEnabled: {Value: config.BoolTrue}, + } + if runtime.GOOS == wslgGoosWindows { + require.ErrorIs(t, cmd.preflightWSLgContext(cfg), wslg.ErrInvalidTarget) + } else { + require.ErrorIs(t, cmd.preflightWSLgContext(cfg), wslg.ErrUnsupported) + } + require.ErrorIs(t, cmd.preflightWSLgClient(cfg, &fakeWorkspaceClient{}), wslg.ErrUnsupported) +} + +func TestWSLgPreflightRunsFirstInPostResolveWorkspace(t *testing.T) { + cfg := testConfig() + cfg.Current().Options = map[string]config.OptionValue{ + config.ContextOptionWSLgEnabled: {Value: config.BoolTrue}, + } + // The fake has no workspace config, so reaching secrets or provider update + // would fail differently; only an early preflight yields ErrUnsupported. + for _, existed := range []bool{false, true} { + client := &fakeWorkspaceClient{} + err := (&UpCmd{}).postResolveWorkspace(context.Background(), cfg, client, existed) + require.ErrorIs(t, err, wslg.ErrUnsupported) + require.Equal(t, !existed, client.deleted, "only a newly created workspace is removed") + } +} + +func TestWSLgResolvedAgentRejectsUnsupportedDriversAndRuntimes(t *testing.T) { + for _, agent := range []provider.ProviderAgentConfig{ + {Driver: provider.ExternalDriver}, + {Driver: provider.CustomDriver}, + {Driver: provider.DockerDriver, Docker: provider.ProviderDockerDriverConfig{Runtime: "podman"}}, + {Driver: provider.DockerDriver, Docker: provider.ProviderDockerDriverConfig{Runtime: "nerdctl"}}, + } { + require.ErrorIs(t, validateWSLgAgent(agent), wslg.ErrUnsupported) + } + require.NoError( + t, + validateWSLgAgent( + provider.ProviderAgentConfig{ + Driver: provider.DockerDriver, + Docker: provider.ProviderDockerDriverConfig{Runtime: "docker"}, + }, + ), + ) +} diff --git a/e2e/tests/dockerbuildkit/wslg.go b/e2e/tests/dockerbuildkit/wslg.go new file mode 100644 index 0000000000..54b7971cee --- /dev/null +++ b/e2e/tests/dockerbuildkit/wslg.go @@ -0,0 +1,186 @@ +package dockerbuildkit + +import ( + "context" + "encoding/json" + "os" + "path/filepath" + "strings" + + "github.com/devsy-org/devsy/e2e/framework" + pkgconfig "github.com/devsy-org/devsy/pkg/config" + "github.com/devsy-org/devsy/pkg/wslg" + "github.com/onsi/ginkgo/v2" + "github.com/onsi/gomega" +) + +const ( + wslgTestWindows = "windows" + wslgNamespace = "DEVSY_WSLG_" +) + +// assertWSLgContainer checks the workspace's current container, which changes on recreate. +func assertWSLgContainer(ctx context.Context, env []string, uid, display string) { + ginkgo.GinkgoHelper() + id := dockerOutput( + ctx, + env, + "ps", + "-q", + "--filter", + "label="+pkgconfig.DevcontainerIDLabel+"="+uid, + ) + gomega.Expect(id).NotTo(gomega.BeEmpty()) + actual := dockerOutput(ctx, env, "inspect", "--format", "{{json .Config.Env}}", id) + var containerEnv []string + framework.ExpectNoError(json.Unmarshal([]byte(actual), &containerEnv)) + gomega.Expect(containerEnv).To(gomega.ContainElement("DISPLAY=" + display)) + for _, entry := range containerEnv { + gomega.Expect(strings.HasPrefix(entry, wslgNamespace)).To( + gomega.BeFalse(), + "discovery must not inject ordinary container environment: %s", entry, + ) + } + gomega.Expect(dockerOutput(ctx, env, "exec", id, "test", "-S", "/tmp/.X11-unix/X0")). + To(gomega.BeEmpty()) +} + +var _ = ginkgo.Describe("WSLg environment transport", ginkgo.Label("wslg"), func() { + ginkgo.DescribeTable("creates and cleans up a workspace using the selected WSL user's display", + func(ctx context.Context, compose bool) { + framework.SkipUnlessOS(wslgTestWindows, "native Windows WSL fixture required") + target := wslg.Target{ + Distro: requireEnv("DEVSY_WSLG_TEST_DISTRO"), + User: requireEnv("DEVSY_WSLG_TEST_USER"), + } + snapshot, err := wslg.Discover(ctx, target) + framework.ExpectNoError(err) + display := snapshot.Environment()[wslg.Display] + gomega.Expect(display). + NotTo(gomega.BeEmpty(), "the X11 transport fixture needs DISPLAY") + host := requireEnv(sshHostEnv) + env := providerEnv(host) + gomega.Expect(dockerOutput(ctx, env, "info", "--format", "{{.ID}}")). + To(gomega.Equal(requireEnv(wslDaemonEnv))) + + // A private Devsy home keeps owner authorization and provider state isolated. + framework.SetEnvForSpec(pkgconfig.EnvHome, ginkgo.GinkgoT().TempDir()) + framework.SetEnvForSpec(pkgconfig.EnvConfig, "") + cwd, err := os.Getwd() + framework.ExpectNoError(err) + f := framework.NewDefaultFramework(filepath.Join(cwd, "bin")) + framework.ExpectNoError( + f.DevsyContextCreate( + ctx, + "wslg-test", + "-o", + "WSLG_ENABLED=true", + "-o", + "WSLG_DISTRO="+target.Distro, + "-o", + "WSLG_USER="+target.User, + // Streaming the development agent over the runner's WSL SSH + // connection can exceed the ordinary 20-second injection budget. + "-o", + "AGENT_INJECT_TIMEOUT=120", + ), + ) + framework.ExpectNoError(f.DevsyContextUse(ctx, "wslg-test")) + framework.ExpectNoError( + f.DevsyProviderAdd( + ctx, + "docker", + "-o", + "DOCKER_HOST="+host, + "-o", + "DOCKER_CONTEXT=", + "-o", + "DOCKER_PATH=docker", + ), + ) + framework.ExpectNoError(f.DevsyProviderUse(ctx, "docker")) + + dir := ginkgo.GinkgoT().TempDir() + image := "ghcr.io/devsy-org/test-images/base:alpine" + config := map[string]any{ + "image": image, + "containerEnv": map[string]string{"DISPLAY": "${localEnv:DEVSY_WSLG_DISPLAY}"}, + "runArgs": []string{ + "--mount", + "type=bind,source=/tmp/.X11-unix,target=/tmp/.X11-unix,readonly", + }, + } + if compose { + config = map[string]any{ + "dockerComposeFile": "compose.yaml", + "service": "dev", + "workspaceFolder": "/workspaces/test", + } + framework.ExpectNoError( + os.WriteFile( + filepath.Join(dir, "compose.yaml"), + []byte( + "services:\n dev:\n image: "+image+` + command: sleep infinity + environment: + DISPLAY: ${DEVSY_WSLG_DISPLAY:?required} + volumes: + - type: bind + source: /tmp/.X11-unix + target: /tmp/.X11-unix + read_only: true + bind: + create_host_path: false +`, + ), + 0o600, + ), + ) + } + data, err := json.Marshal(config) + framework.ExpectNoError(err) + framework.ExpectNoError( + os.WriteFile(filepath.Join(dir, ".devcontainer.json"), data, 0o600), + ) + ginkgo.DeferCleanup( + func(ctx context.Context) { framework.ExpectNoError(f.DevsyWorkspaceDelete(ctx, dir)) }, + ) + framework.ExpectNoError(f.DevsyUp(ctx, dir, "--ide", "none")) + workspace, err := f.FindWorkspace(ctx, dir) + framework.ExpectNoError(err) + assertWSLgContainer(ctx, env, workspace.UID, display) + + framework.ExpectNoError(f.DevsyStop(ctx, dir)) + _, stderr, err := f.ExecCommandCapture( + ctx, + []string{"workspace", "up", dir, "--ide", "none"}, + ) + gomega.Expect(err).To(gomega.HaveOccurred()) + gomega.Expect(stderr).To(gomega.ContainSubstring("--recreate")) + framework.ExpectNoError(f.DevsyUp(ctx, dir, "--ide", "none", "--recreate")) + // The earlier container is gone, so look it up again. + assertWSLgContainer(ctx, env, workspace.UID, display) + // Invalidate discovery while the Docker daemon remains reachable. Stop and + // delete must replay metadata rather than execute this unavailable target. + _, _, err = f.ExecCommandCapture( + ctx, + []string{"context", "set", "-o", "WSLG_DISTRO=devsy-ci-missing-distro"}, + ) + framework.ExpectNoError(err) + framework.ExpectNoError(f.DevsyStop(ctx, dir)) + ginkgo.AddReportEntry( + "WSLg acceptance scope", + strings.Join( + []string{ + "Native WSL printenv, image/Compose interpolation and daemon-visible X11 socket tested.", + "Stopped-container recreation and cleanup tested.", + "Visible Windows windows and native Wayland rendering require manual acceptance.", + }, + " ", + ), + ) + }, + ginkgo.Entry("image devcontainer", false, ginkgo.SpecTimeout(framework.TimeoutLong())), + ginkgo.Entry("Compose devcontainer", true, ginkgo.SpecTimeout(framework.TimeoutLong())), + ) +}) diff --git a/hack/ci/e2e.go b/hack/ci/e2e.go index 0ec8816977..208fe2a329 100644 --- a/hack/ci/e2e.go +++ b/hack/ci/e2e.go @@ -25,6 +25,8 @@ const ( executableMode = fs.FileMode(0o755) windowsDockerHost = "npipe:////./pipe/podman-machine-default" windowsDockerWSLHost = "npipe:////./pipe/devsy-ci-no-daemon" + wslgTestDistro = "Ubuntu-24.04" + wslgTestUser = "devsyci" reportNameSuffix = "-report.json" postCheckDockerInstalled = "docker-installed" @@ -362,10 +364,16 @@ func (r e2eRunner) e2eEnv(suite Suite) []string { } // dockerEnv returns the Docker client variables of the suite. A docker-wsl suite talks to the -// WSL2 fixture and clears DOCKER_CONTEXT so that the explicit host is used. +// WSL2 fixture and clears DOCKER_CONTEXT so that the explicit host is used. It also names the +// fixture distro and user for the WSLg specs. func (r e2eRunner) dockerEnv(suite Suite) []string { if suite.Runtime == runtimeDockerWSL { - return []string{"DOCKER_HOST=" + windowsDockerWSLHost, "DOCKER_CONTEXT="} + return []string{ + "DOCKER_HOST=" + windowsDockerWSLHost, + "DOCKER_CONTEXT=", + "DEVSY_WSLG_TEST_DISTRO=" + wslgTestDistro, + "DEVSY_WSLG_TEST_USER=" + wslgTestUser, + } } if dockerHost := r.dockerHost(); dockerHost != "" { return []string{"DOCKER_HOST=" + dockerHost} diff --git a/hack/ci/e2e_test.go b/hack/ci/e2e_test.go index 3f84f6758e..9878b842ae 100644 --- a/hack/ci/e2e_test.go +++ b/hack/ci/e2e_test.go @@ -279,6 +279,10 @@ func (s *E2ECommandSuite) TestRunDockerWSLUsesWSLDaemonAndClearsContext() { dockerContext, ok := e2eEnvValue(spec.Env, "DOCKER_CONTEXT") s.True(ok, "DOCKER_CONTEXT must be present so an inherited context is cleared") s.Empty(dockerContext) + distro, _ := e2eEnvValue(spec.Env, "DEVSY_WSLG_TEST_DISTRO") + s.Equal("Ubuntu-24.04", distro) + user, _ := e2eEnvValue(spec.Env, "DEVSY_WSLG_TEST_USER") + s.Equal("devsyci", user) } func (s *E2ECommandSuite) TestRunWithoutDockerWSLLeavesDockerContextUnset() { diff --git a/hack/ci/suites.yaml b/hack/ci/suites.yaml index 9c1e8e76e3..cf29fd96d0 100644 --- a/hack/ci/suites.yaml +++ b/hack/ci/suites.yaml @@ -101,6 +101,14 @@ unit: run: '^(TestInvocationSuite|TestProviderDaemonOverrides.*|TestStdioTransportSuite|TestLaunch.*|TestEnvBlock.*)$' args: [-race, -count=1, -v, -timeout=5m] + - name: windows-wslg-boundaries + description: WSLg preflight, discovery and Compose environment boundaries on native Windows + os: [windows] + packages: [./cmd/workspace/up, ./pkg/wslg, ./pkg/compose, ./pkg/devcontainer] + run: '^TestWSLg' + require_tests: [TestWSLgSuite, TestWSLgPreflightBeforeWorkspaceProvisioning] + args: [-race, -count=1, -timeout=5m] + - name: ci-tooling-windows description: Go CI helpers that also run on Windows os: [windows] @@ -267,6 +275,15 @@ e2e: expected_spec_count: 6 test_timeout: 900s job_timeout_minutes: 25 + # Same fixture, own job: the specs create real workspaces through the + # selected WSL user's display, and the job also runs the Compose parity probe. + - group: integration + label: wslg + runner: windows-latest + runtime: docker-wsl + expected_spec_count: 2 + test_timeout: 600s + job_timeout_minutes: 40 # --- microsandbox --- - { group: microsandbox, label: up-provider-microsandbox, expected_spec_count: 2, performance_capture: true } diff --git a/pkg/compose/helper.go b/pkg/compose/helper.go index c892f88cbb..496e7ac9e3 100644 --- a/pkg/compose/helper.go +++ b/pkg/compose/helper.go @@ -6,31 +6,60 @@ import ( "encoding/json" "fmt" "io" + "maps" "os" "os/exec" "regexp" + "runtime" "strings" "github.com/blang/semver/v4" composecli "github.com/compose-spec/compose-go/v2/cli" + "github.com/compose-spec/compose-go/v2/dotenv" composetypes "github.com/compose-spec/compose-go/v2/types" pkgconfig "github.com/devsy-org/devsy/pkg/config" "github.com/devsy-org/devsy/pkg/devcontainer/config" "github.com/devsy-org/devsy/pkg/docker" "github.com/devsy-org/devsy/pkg/log" + "github.com/devsy-org/devsy/pkg/wslg" ) -const projectNameFlag = "--project-name" +const ( + goosWindows = "windows" + projectNameFlag = "--project-name" +) func LoadDockerComposeProject( ctx context.Context, paths []string, envFiles []string, ) (*composetypes.Project, error) { + return LoadDockerComposeProjectWithEnv(ctx, paths, envFiles, nil) +} + +func LoadDockerComposeProjectWithEnv( + ctx context.Context, + paths, envFiles []string, + candidates map[string]string, +) (*composetypes.Project, error) { + if candidates != nil { + if err := wslg.CheckCollisions( + "process environment", + os.Environ(), + runtime.GOOS == goosWindows, + ); err != nil { + return nil, err + } + } + if err := wslg.ValidateEnvironment(candidates); err != nil { + return nil, err + } projectOptions, err := composecli.NewProjectOptions( paths, composecli.WithOsEnv, + composecli.WithEnv(wslg.Pairs(candidates)), composecli.WithEnvFiles(envFiles...), + checkWSLgEnvFiles(candidates), composecli.WithDotEnv, composecli.WithDefaultProfiles(), ) @@ -47,10 +76,43 @@ func LoadDockerComposeProject( } type ComposeHelper struct { - Command string - Version string - Args []string - Docker *docker.DockerHelper + Command string + Version string + Args []string + Docker *docker.DockerHelper + invocationEnvironment map[string]string +} + +// WithInvocationEnvironment leaves the shared provider helper unchanged. +func (h *ComposeHelper) WithInvocationEnvironment(env map[string]string) *ComposeHelper { + clone := *h + clone.Args = append([]string(nil), h.Args...) + clone.invocationEnvironment = maps.Clone(env) + return &clone +} + +func checkWSLgEnvFiles(candidates map[string]string) composecli.ProjectOptionsFn { + return func(options *composecli.ProjectOptions) error { + if candidates == nil { + return nil + } + // Parse each source with Compose's own dotenv parser so even shadowed and + // empty assignments count. Service env_file is a different namespace. + for _, file := range options.EnvFiles { + env, err := dotenv.GetEnvFromFile(options.Environment, []string{file}) + if err != nil { + return fmt.Errorf("cannot validate WSLg interpolation file %s", file) + } + if err := wslg.CheckCollisions( + file, + wslg.Pairs(env), + runtime.GOOS == goosWindows, + ); err != nil { + return err + } + } + return nil + } } // NewComposeHelper creates a new ComposeHelper instance after detecting whether @@ -370,6 +432,12 @@ func (h *ComposeHelper) buildCmd(ctx context.Context, args ...string) *exec.Cmd if h.Docker != nil && h.Docker.Environment != nil { cmd.Env = append(os.Environ(), h.Docker.Environment...) } + if h.invocationEnvironment != nil { + if cmd.Env == nil { + cmd.Env = os.Environ() + } + cmd.Env = wslg.Overlay(cmd.Env, h.invocationEnvironment, runtime.GOOS == goosWindows) + } return cmd } diff --git a/pkg/compose/wslg_test.go b/pkg/compose/wslg_test.go new file mode 100644 index 0000000000..4f6dc6a754 --- /dev/null +++ b/pkg/compose/wslg_test.go @@ -0,0 +1,172 @@ +package compose + +import ( + "bytes" + "context" + "os" + "os/exec" + "path/filepath" + "runtime" + "testing" + + "github.com/devsy-org/devsy/pkg/docker" + "github.com/devsy-org/devsy/pkg/wslg" + "github.com/stretchr/testify/suite" +) + +type WSLgSuite struct{ suite.Suite } + +func TestWSLgSuite(t *testing.T) { suite.Run(t, new(WSLgSuite)) } + +func (s *WSLgSuite) TestLoaderRequiredInterpolationAndEmptyValues() { + path := s.fixture( + `services: + dev: + image: alpine + environment: + DISPLAY: ${DEVSY_WSLG_DISPLAY:?required} + EMPTY: ${DEVSY_WSLG_XDG_RUNTIME_DIR-default} + ABSENT: ${DEVSY_WSLG_WAYLAND_DISPLAY-default} +`, + ) + _, err := LoadDockerComposeProject(context.Background(), []string{path}, nil) + s.Error(err) + project, err := LoadDockerComposeProjectWithEnv( + context.Background(), + []string{path}, + nil, + map[string]string{wslg.Display: ":0$literal", wslg.RuntimeDir: ""}, + ) + s.Require().NoError(err) + s.Equal(":0$literal", *project.Services["dev"].Environment["DISPLAY"]) + s.Equal("", *project.Services["dev"].Environment["EMPTY"]) + s.Equal("default", *project.Services["dev"].Environment["ABSENT"]) + _, set := os.LookupEnv(wslg.Display) + s.False(set) +} + +func (s *WSLgSuite) TestDotenvCollisionsIncludingEmptyAndShadowed() { + path := s.fixture("services:\n dev:\n image: alpine\n") + file := filepath.Join(filepath.Dir(path), ".env") + for _, line := range []string{ + "DEVSY_WSLG_DISPLAY=", + "export DEVSY_WSLG_WAYLAND_DISPLAY='hidden'", + "DEVSY_WSLG_XDG_RUNTIME_DIR=first\nDEVSY_WSLG_XDG_RUNTIME_DIR=", + } { + s.Require().NoError(os.WriteFile(file, []byte(line), 0o600)) + for _, files := range [][]string{nil, {file}} { + _, err := LoadDockerComposeProjectWithEnv( + context.Background(), + []string{path}, + files, + map[string]string{wslg.Display: ":0"}, + ) + s.ErrorIs(err, wslg.ErrCollision) + if err != nil { + s.NotContains(err.Error(), "hidden") + } + } + _, err := LoadDockerComposeProject(context.Background(), []string{path}, []string{file}) + s.NoError(err, "disabled path preserves normal dotenv precedence") + } +} + +func (s *WSLgSuite) TestServiceEnvFileIsNotInterpolationSource() { + path := s.fixture( + `services: + dev: + image: alpine + env_file: ./service.env + environment: + DISPLAY: ${DEVSY_WSLG_DISPLAY:?required} +`, + ) + s.Require().NoError(os.WriteFile( + filepath.Join(filepath.Dir(path), "service.env"), + []byte("DEVSY_WSLG_DISPLAY=service-only"), 0o600, + )) + project, err := LoadDockerComposeProjectWithEnv( + context.Background(), + []string{path}, + nil, + map[string]string{wslg.Display: ":0"}, + ) + s.Require().NoError(err) + s.Equal("service-only", *project.Services["dev"].Environment[wslg.Display]) + s.Equal(":0", *project.Services["dev"].Environment["DISPLAY"]) +} + +func (s *WSLgSuite) TestScopedChildEnvironment() { + helper := &ComposeHelper{ + Command: "unused", + Docker: &docker.DockerHelper{ + Environment: []string{"PROVIDER_VAR=keep", wslg.Display + "=old"}, + }, + } + env := map[string]string{wslg.Display: ":0", wslg.RuntimeDir: ""} + scoped := helper.WithInvocationEnvironment(env) + env[wslg.Display] = "mutated" + cmd := scoped.buildCmd(context.Background(), "config") + s.Contains(cmd.Env, "PROVIDER_VAR=keep") + s.Contains(cmd.Env, wslg.Display+"=:0") + s.Contains(cmd.Env, wslg.RuntimeDir+"=") + s.NotContains(cmd.Env, wslg.Display+"=old") + s.Nil(helper.invocationEnvironment) +} + +// This exercises both consumers without a daemon. CI installs Compose on the +// Windows WSL job and requires this test rather than accepting a local skip. +func (s *WSLgSuite) TestInstalledComposeParity() { + path, err := exec.LookPath("docker") + if err != nil { + s.T().Skip("Docker CLI unavailable") + } + //nolint:gosec // Resolve the installed Docker CLI for this integration test. + if err := exec.Command(path, "compose", "version").Run(); err != nil { + s.T().Skip("Compose unavailable") + } + file := s.fixture( + `name: wslg-parity +services: + dev: + image: alpine + environment: + DISPLAY: ${DEVSY_WSLG_DISPLAY:?required} + EMPTY: ${DEVSY_WSLG_XDG_RUNTIME_DIR-default} +`, + ) + candidates := map[string]string{wslg.Display: ":0$literal", wslg.RuntimeDir: ""} + project, err := LoadDockerComposeProjectWithEnv( + context.Background(), + []string{file}, + nil, + candidates, + ) + s.Require().NoError(err) + helper := (&ComposeHelper{Command: path, Args: []string{"compose"}}).WithInvocationEnvironment( + candidates, + ) + var stdout, stderr bytes.Buffer + err = helper.Run( + context.Background(), + []string{"-f", file, "config", "--format", "json"}, + docker.Streams{Stdout: &stdout, Stderr: &stderr}, + ) + s.Require().NoError(err, stderr.String()) + // `compose config` escapes dollars for a reusable Compose document. Load + // that document once to compare runtime values, not its serialized escaping. + rendered := filepath.Join(s.T().TempDir(), "rendered.json") + s.Require().NoError(os.WriteFile(rendered, stdout.Bytes(), 0o600)) + actual, err := LoadDockerComposeProject(context.Background(), []string{rendered}, nil) + s.Require().NoError(err) + for _, key := range []string{"DISPLAY", "EMPTY"} { + s.Equal(*project.Services["dev"].Environment[key], *actual.Services["dev"].Environment[key]) + } + s.T().Logf("loader/CLI parity on %s", runtime.GOOS) +} + +func (s *WSLgSuite) fixture(content string) string { + path := filepath.Join(s.T().TempDir(), "compose.yaml") + s.Require().NoError(os.WriteFile(path, []byte(content), 0o600)) + return path +} diff --git a/pkg/config/context.go b/pkg/config/context.go index f328b0966a..bc1f6d9b9a 100644 --- a/pkg/config/context.go +++ b/pkg/config/context.go @@ -30,6 +30,9 @@ const ( ContextOptionSecretsBackend = "SECRETS_BACKEND" ContextOptionSnapshotRegistry = "SNAPSHOT_REGISTRY" ContextOptionLogLevel = "LOG_LEVEL" + ContextOptionWSLgEnabled = "WSLG_ENABLED" + ContextOptionWSLgDistro = "WSLG_DISTRO" + ContextOptionWSLgUser = "WSLG_USER" ) var ContextOptions = []ContextOption{ @@ -39,6 +42,20 @@ var ContextOptions = []ContextOption{ Default: BoolFalse, Enum: []string{BoolTrue, BoolFalse}, }, + { + Name: ContextOptionWSLgEnabled, + Description: "Discover WSLg display values for local Windows Docker workspaces (experimental)", + Default: BoolFalse, + Enum: []string{BoolTrue, BoolFalse}, + }, + { + Name: ContextOptionWSLgDistro, + Description: "Exact WSL2 distribution containing the Docker daemon and WSLg session", + }, + { + Name: ContextOptionWSLgUser, + Description: "Non-root WSL user whose display values should be discovered", + }, { Name: ContextOptionSSHAddPrivateKeys, Description: "Specifies if Devsy should automatically add ssh-keys to the ssh-agent", diff --git a/pkg/config/context_test.go b/pkg/config/context_test.go index 9aaddf64d1..5f0ab10e1e 100644 --- a/pkg/config/context_test.go +++ b/pkg/config/context_test.go @@ -111,3 +111,10 @@ func TestLogLevelOption_DefaultAndEnum(t *testing.T) { } t.Fatal("LOG_LEVEL must be a registered context option") } + +func TestWSLgOptionsDefaultOff(t *testing.T) { + c := &Config{Contexts: map[string]*ContextConfig{"default": {}}, DefaultContext: "default"} + require.False(t, c.ContextOptionBool(ContextOptionWSLgEnabled)) + require.Empty(t, c.ContextOption(ContextOptionWSLgDistro)) + require.Empty(t, c.ContextOption(ContextOptionWSLgUser)) +} diff --git a/pkg/devcontainer/compose.go b/pkg/devcontainer/compose.go index f691e73701..988f781632 100644 --- a/pkg/devcontainer/compose.go +++ b/pkg/devcontainer/compose.go @@ -4,6 +4,7 @@ import ( "context" "encoding/json" "fmt" + "maps" "os" "path/filepath" "slices" @@ -28,6 +29,7 @@ const ( FeaturesStartOverrideFilePrefix = "docker-compose.devcontainer.containerFeatures" composeProjectNameFlag = "--project-name" + composeProjectDirFlag = "--project-directory" ) type composeProjectFiles struct { @@ -107,7 +109,26 @@ func (r *runner) composeHelper() (*compose.ComposeHelper, error) { ) } - return composeDriver.ComposeHelper() + helper, err := composeDriver.ComposeHelper() + if err != nil { + return nil, err + } + if r.wslgSnapshot != nil { + return helper.WithInvocationEnvironment(r.wslgSnapshot.Environment()), nil + } + return helper, nil +} + +// Only a v2 label carries a recorded environment; without one, keep whatever +// the helper already has so legacy teardown can still resolve its variables. +func replayComposeEnvironment( + helper *compose.ComposeHelper, + env map[string]string, +) *compose.ComposeHelper { + if env == nil { + return helper + } + return helper.WithInvocationEnvironment(env) } func (r *runner) stopDockerCompose(ctx context.Context, projectName string) error { @@ -121,7 +142,7 @@ func (r *runner) stopDockerCompose(ctx context.Context, projectName string) erro return fmt.Errorf("get original Compose invocation: %w", err) } - err = composeHelper.Stop(ctx, projectName, args) + err = replayComposeEnvironment(composeHelper, args.WSLgEnv).Stop(ctx, projectName, args.Args) if err != nil { return err } @@ -144,7 +165,8 @@ func (r *runner) deleteDockerCompose( return fmt.Errorf("get original Compose invocation: %w", err) } - err = composeHelper.Remove(ctx, projectName, args, removeVolumes) + err = replayComposeEnvironment(composeHelper, args.WSLgEnv). + Remove(ctx, projectName, args.Args, removeVolumes) if err != nil { return err } @@ -240,10 +262,11 @@ func (r *runner) loadComposeProject( projFiles composeProjectFiles, ) (*composetypes.Project, error) { log.Debugf("Loading docker compose project %+v", projFiles.composeFiles) - project, err := compose.LoadDockerComposeProject( + project, err := compose.LoadDockerComposeProjectWithEnv( ctx, projFiles.composeFiles, projFiles.envFiles, + r.wslgSnapshot.Environment(), ) if err != nil { return nil, fmt.Errorf("load docker compose project: %w", err) @@ -337,6 +360,9 @@ func (r *runner) ensureComposeContainer( if err != nil { return nil, fmt.Errorf("find dev container: %w", err) } + if err := r.checkWSLgReuse(containerDetails, options.Recreate); err != nil { + return nil, err + } effectiveOptions, forceSecretRuntimeRefresh, err := r.composeSecretRuntimeOptions( containerDetails, options, @@ -1086,12 +1112,20 @@ func (r *runner) buildComposeOverrideArgs( if override.path != "" { composeGlobalArgs = append(composeGlobalArgs, "-f", override.path) - if err := recordComposeInvocation( - override.path, - start.parsedConfig.Config.Service, - start.project.WorkingDir, - composeGlobalArgs, - ); err != nil { + invocation := composeInvocation{ + Version: 1, + Directory: start.project.WorkingDir, + Args: composeGlobalArgs, + } + if replay := r.wslgReplay(); replay != nil { + invocation.Version = 2 + invocation.WSLg = replay + } + if err := recordComposeInvocation(composeInvocationRecord{ + Path: override.path, + Service: start.parsedConfig.Config.Service, + Invocation: invocation, + }); err != nil { return composeOverrideArgs{}, err } } @@ -1195,9 +1229,16 @@ func (r *runner) generateComposeUpOverride( if err != nil { return composeOverrideFile{}, err } - additionalLabels := composeOverrideLabels( + additionalLabels, err := r.wslgLabels() + if err != nil { + return composeOverrideFile{}, err + } + if additionalLabels == nil { + additionalLabels = map[string]string{} + } + maps.Copy(additionalLabels, composeOverrideLabels( imageDetails, metadataValue, contract, structuralSignature(start.parsedConfig.Config), - ) + )) overrideComposeUpFilePath, err := r.extendedDockerComposeUp(&composeUpParams{ parsedConfig: start.parsedConfig, mergedConfig: mergedConfig, diff --git a/pkg/devcontainer/compose_metadata_test.go b/pkg/devcontainer/compose_metadata_test.go index a8bc23b578..7ed9015c8b 100644 --- a/pkg/devcontainer/compose_metadata_test.go +++ b/pkg/devcontainer/compose_metadata_test.go @@ -260,7 +260,7 @@ func TestComposeResumePreservesSavedInvocation(t *testing.T) { require.Equal(t, []string{ composeProjectNameFlag, composeTestProject, - "--project-directory", + composeProjectDirFlag, dir, composeTestEnvFlag, envFile, diff --git a/pkg/devcontainer/compose_resume.go b/pkg/devcontainer/compose_resume.go index 6f96ae75c2..4be2707a1b 100644 --- a/pkg/devcontainer/compose_resume.go +++ b/pkg/devcontainer/compose_resume.go @@ -105,6 +105,9 @@ func (r *runner) startComposeInstance( params *composeContainerParams, details *config.ContainerDetails, ) (*config.ContainerDetails, error) { + if err := checkWSLgResume(details); err != nil { + return nil, err + } args, err := composeResumeArgs(details, params.project.Name) if err != nil { return nil, err @@ -147,7 +150,7 @@ func composeResumeArgs(details *config.ContainerDetails, projectName string) ([] return nil, err } if found { - return append(args, persisted...), nil + return append(args, persisted.Args...), nil } for _, file := range files { args = append(args, "-f", file) diff --git a/pkg/devcontainer/compose_up.go b/pkg/devcontainer/compose_up.go index f1079f4fc4..93156e0065 100644 --- a/pkg/devcontainer/compose_up.go +++ b/pkg/devcontainer/compose_up.go @@ -71,7 +71,7 @@ func (r *runner) generateDockerComposeUpProject(params *composeUpParams) *compos overrideService := &composetypes.ServiceConfig{ Name: composeService.Name, Entrypoint: buildOverrideEntrypoint(mergedConfig, userEntrypoint), - Environment: mappingFromMap(containerEnv), + Environment: r.composeContainerEnvironment(containerEnv), Init: mergedConfig.Init, CapAdd: mergedConfig.CapAdd, SecurityOpt: mergedConfig.SecurityOpt, @@ -117,6 +117,19 @@ func (r *runner) generateDockerComposeUpProject(params *composeUpParams) *compos return project } +// ContainerEnv has already undergone devcontainer substitution. Discovered +// values are data and must survive Compose's later interpolation unchanged. +func (r *runner) composeContainerEnvironment(env map[string]string) composetypes.MappingWithEquals { + if r.wslgSnapshot == nil { + return mappingFromMap(env) + } + escaped := make(map[string]string, len(env)) + for key, value := range env { + escaped[key] = composeLabelEscaper.Replace(value) + } + return mappingFromMap(escaped) +} + // resolveServiceEntrypoint determines the effective entrypoint and command for // the overridden service. When OverrideCommand is set both are cleared so the // devcontainer entrypoint takes over; otherwise the service values fall back to diff --git a/pkg/devcontainer/config.go b/pkg/devcontainer/config.go index 9b602dabf2..e0efde3176 100644 --- a/pkg/devcontainer/config.go +++ b/pkg/devcontainer/config.go @@ -649,6 +649,8 @@ func (r *runner) buildSubstitutionContext( maps.Copy(env, config.ListToObject(options.InitEnv)) } + maps.Copy(env, r.wslgSnapshot.Environment()) + return &config.SubstitutionContext{ DevContainerID: config.DeriveDevContainerID(r.localWorkspaceFolder, configFile), LocalWorkspaceFolder: r.localWorkspaceFolder, diff --git a/pkg/devcontainer/config_overlay_lifecycle.go b/pkg/devcontainer/config_overlay_lifecycle.go index 0471e848dd..2f83b5edbf 100644 --- a/pkg/devcontainer/config_overlay_lifecycle.go +++ b/pkg/devcontainer/config_overlay_lifecycle.go @@ -8,6 +8,8 @@ import ( "fmt" "os" "path/filepath" + "strings" + "unicode/utf8" composetypes "github.com/compose-spec/compose-go/v2/types" "github.com/devsy-org/devsy/pkg/compose" @@ -140,6 +142,9 @@ func (r *runner) checkOverlayRecreation( if err != nil { return err } + if err := r.checkWSLgReuseFor(parsed.Config, details, options.Recreate); err != nil { + return err + } if details != nil { if err := r.checkComposeFeatureRecreation(details, parsed, options); err != nil { return err @@ -283,27 +288,37 @@ func (r *runner) validateOverlayDockerfileAssets(parsed *config.SubstitutedConfi } type composeInvocation struct { - Version int `json:"version"` - Args []string `json:"args"` - Directory string `json:"directory"` + Version int `json:"version"` + Args []string `json:"args"` + Directory string `json:"directory"` + WSLg *wslgReplay `json:"wslg,omitempty"` +} + +type composeTeardownInvocation struct { + Args []string + WSLgEnv map[string]string } -func (r *runner) composeTeardownArgs(ctx context.Context, projectName string) ([]string, error) { +func (r *runner) composeTeardownArgs( + ctx context.Context, + projectName string, +) (*composeTeardownInvocation, error) { details, err := r.driver.FindDevContainer(ctx, r.id) if err != nil { return nil, err } - args, found, err := persistedComposeInvocationArgs(details, projectName) + invocation, found, err := persistedComposeInvocationArgs(details, projectName) if found || err != nil { - return args, err + return invocation, err } - return r.legacyComposeTeardownArgs(ctx, projectName) + args, err := r.legacyComposeTeardownArgs(ctx, projectName) + return &composeTeardownInvocation{Args: args}, err } func persistedComposeInvocationArgs( details *config.ContainerDetails, projectName string, -) ([]string, bool, error) { +) (*composeTeardownInvocation, bool, error) { if details == nil || details.Config.Labels[pkgconfig.ComposeProjectLabel] != projectName { return nil, false, nil } @@ -312,14 +327,18 @@ func persistedComposeInvocationArgs( return nil, false, nil } var invocation composeInvocation - if err := json.Unmarshal([]byte(value), &invocation); err != nil { - return nil, true, fmt.Errorf("read persisted Compose invocation: %w", err) + if err := decodeWSLgMetadata(value, &invocation); err != nil { + return nil, true, fmt.Errorf("invalid persisted Compose invocation") } if err := validateComposeInvocation(invocation); err != nil { return nil, true, err } - args := append([]string{"--project-directory", invocation.Directory}, invocation.Args...) - return args, true, nil + args := append([]string{composeProjectDirFlag, invocation.Directory}, invocation.Args...) + result := &composeTeardownInvocation{Args: args} + if invocation.WSLg != nil { + result.WSLgEnv = invocation.WSLg.Environment + } + return result, true, nil } func validateComposeInvocation(invocation composeInvocation) error { @@ -330,18 +349,30 @@ func validateComposeInvocation(invocation composeInvocation) error { if invocation.Args[i] != "-f" && invocation.Args[i] != "--env-file" { return fmt.Errorf("invalid persisted Compose argument %q", invocation.Args[i]) } - if invocation.Args[i+1] == "" { - return fmt.Errorf("empty persisted Compose path") + if invocation.Args[i+1] == "" || !utf8.ValidString(invocation.Args[i+1]) || + strings.ContainsAny(invocation.Args[i+1], "\x00\r\n") { + return fmt.Errorf("invalid persisted Compose path") } } return nil } func validateComposeInvocationHeader(invocation composeInvocation) error { - if invocation.Version != 1 || invocation.Directory == "" || len(invocation.Args) == 0 || + if (invocation.Version != 1 && invocation.Version != 2) || invocation.Directory == "" || + len(invocation.Args) == 0 || len(invocation.Args)%2 != 0 { return fmt.Errorf("invalid persisted Compose invocation") } + if !utf8.ValidString(invocation.Directory) || + strings.ContainsAny(invocation.Directory, "\x00\r\n") { + return fmt.Errorf("invalid persisted Compose directory") + } + if invocation.Version == 2 { + return validateWSLgReplay(invocation.WSLg) + } + if invocation.WSLg != nil { + return fmt.Errorf("unexpected WSLg metadata in v1 Compose invocation") + } return nil } @@ -418,7 +449,7 @@ func (r *runner) composeTeardownArgsWithExistingFiles( } } return append( - []string{"--project-directory", legacy.project.WorkingDir}, + []string{composeProjectDirFlag, legacy.project.WorkingDir}, files.composeGlobalArgs...), nil } @@ -456,7 +487,17 @@ func (r *runner) lastResolvedConfigOrigin(last *config.DevContainerConfigWithPat // The generated override must include its own path in the invocation label. // Update the YAML before Compose consumes it, after its final filename is known. -func recordComposeInvocation(path, service, directory string, args []string) error { +type composeInvocationRecord struct { + Path string + Service string + Invocation composeInvocation +} + +func recordComposeInvocation(record composeInvocationRecord) error { + path, service := record.Path, record.Service + if err := validateComposeInvocation(record.Invocation); err != nil { + return err + } // #nosec G304 -- the caller passes the generated Compose override path. data, err := os.ReadFile(path) if err != nil { @@ -472,7 +513,7 @@ func recordComposeInvocation(path, service, directory string, args []string) err } if err := appendComposeInvocationLabel( labels, - composeInvocation{Version: 1, Directory: directory, Args: args}, + record.Invocation, ); err != nil { return err } diff --git a/pkg/devcontainer/config_overlay_recreation_test.go b/pkg/devcontainer/config_overlay_recreation_test.go index 5a7763994f..a95677f779 100644 --- a/pkg/devcontainer/config_overlay_recreation_test.go +++ b/pkg/devcontainer/config_overlay_recreation_test.go @@ -308,7 +308,7 @@ func TestComposeTeardownArgsUsesPersistedInvocation(t *testing.T) { got, err := r.composeTeardownArgs(context.Background(), "project-name") require.NoError(t, err) - require.Equal(t, append([]string{"--project-directory", projectDir}, args...), got) + require.Equal(t, append([]string{composeProjectDirFlag, projectDir}, args...), got.Args) } func TestComposeTeardownArgsRejectsMalformedInvocation(t *testing.T) { @@ -359,7 +359,16 @@ func TestRecordComposeInvocationRoundTrip(t *testing.T) { contents := "services:\n " + composeDevService + ":\n labels:\n devsy.overlay.structure: v1:test\n" require.NoError(t, os.WriteFile(overridePath, []byte(contents), 0o600)) - require.NoError(t, recordComposeInvocation(overridePath, service, directory, args)) + require.NoError( + t, + recordComposeInvocation( + composeInvocationRecord{ + Path: overridePath, + Service: service, + Invocation: composeInvocation{Version: 1, Directory: directory, Args: args}, + }, + ), + ) // #nosec G304 -- overridePath was created beneath t.TempDir above. data, err := os.ReadFile(overridePath) diff --git a/pkg/devcontainer/prebuild.go b/pkg/devcontainer/prebuild.go index 9b115fffdb..579164f776 100644 --- a/pkg/devcontainer/prebuild.go +++ b/pkg/devcontainer/prebuild.go @@ -13,6 +13,10 @@ import ( ) func (r *runner) Build(ctx context.Context, options provider.BuildOptions) (string, error) { + if err := r.prepareWSLg(ctx, options.CLIOptions); err != nil { + return "", err + } + defer func() { r.wslgSnapshot = nil }() if err := r.prepareStandaloneBuild(); err != nil { return "", err } diff --git a/pkg/devcontainer/run.go b/pkg/devcontainer/run.go index 31b252cd92..aba3bf56e9 100644 --- a/pkg/devcontainer/run.go +++ b/pkg/devcontainer/run.go @@ -17,6 +17,7 @@ import ( "github.com/devsy-org/devsy/pkg/provider" "github.com/devsy-org/devsy/pkg/status" "github.com/devsy-org/devsy/pkg/workspacelogs" + "github.com/devsy-org/devsy/pkg/wslg" ) // Runner drives the lifecycle of a single workspace's dev container. @@ -107,7 +108,8 @@ type runner struct { imageDetails *config.ImageDetails imageDetailsImage string - reporter status.Reporter + reporter status.Reporter + wslgSnapshot *wslg.Snapshot } func NewRunner( @@ -159,6 +161,10 @@ func (r *runner) Up( reporter = status.Nop() } r.reporter = reporter + if err := r.prepareWSLg(ctx, options.CLIOptions); err != nil { + return nil, err + } + defer func() { r.wslgSnapshot = nil }() selectionWarning := r.compatibilitySelectionWarning( r.effectiveDevContainerSelection(options.CLIOptions), ) @@ -181,6 +187,14 @@ func (r *runner) Up( } } + if defaultSelection { + // The full overlay check runs after initializeCommand; fail a stale + // WSLg container first so the host hook does not run twice. + err = r.checkWSLgReuseBeforeInitialize(ctx, substitutedConfig.Config, options) + if err != nil { + return nil, err + } + } if err := r.runInitializePhase(ctx, reporter, substitutedConfig, options); err != nil { return nil, err } diff --git a/pkg/devcontainer/single.go b/pkg/devcontainer/single.go index 68bec2816f..3e08fa499d 100644 --- a/pkg/devcontainer/single.go +++ b/pkg/devcontainer/single.go @@ -164,6 +164,11 @@ func (r *runner) prepareContainerRecreation( details *config.ContainerDetails, params *resolveParams, ) error { + if err := r.checkWSLgReuseFor( + params.parsedConfig.Config, details, params.options.Recreate, + ); err != nil { + return err + } if err := r.applyDriverRecreateRequirement(ctx, details, params); err != nil { return err } @@ -979,6 +984,13 @@ func (r *runner) runContainer( runOptions.Labels, overlayStructureLabel+"="+structuralSignature(p.parsedConfig.Config), ) + wslgLabels, err := r.wslgLabels() + if err != nil { + return err + } + for key, value := range wslgLabels { + runOptions.Labels = append(runOptions.Labels, key+"="+value) + } runOptions.AllowRecreate = p.options.Recreate runOptions.Env = r.addExtraEnvVars(runOptions.Env) if r.needsCurrentContainerIdentity() { diff --git a/pkg/devcontainer/wslg.go b/pkg/devcontainer/wslg.go new file mode 100644 index 0000000000..e480e7b383 --- /dev/null +++ b/pkg/devcontainer/wslg.go @@ -0,0 +1,215 @@ +package devcontainer + +import ( + "context" + "encoding/json" + "fmt" + "maps" + "os" + "runtime" + "strings" + "unicode/utf8" + + pkgconfig "github.com/devsy-org/devsy/pkg/config" + "github.com/devsy-org/devsy/pkg/devcontainer/config" + "github.com/devsy-org/devsy/pkg/docker" + "github.com/devsy-org/devsy/pkg/driver" + "github.com/devsy-org/devsy/pkg/provider" + "github.com/devsy-org/devsy/pkg/wslg" +) + +const wslgSnapshotLabel = "devsy.wslg.snapshot" + +// The local context is the authority. Neither agent workspace JSON nor a +// downloaded provider can opt in, and cleanup never calls this method. +func (r *runner) prepareWSLg(ctx context.Context, options provider.CLIOptions) error { + r.wslgSnapshot = nil + if r.workspaceConfig == nil || r.workspaceConfig.Workspace == nil { + return nil + } + cfg, err := pkgconfig.LoadConfig(r.workspaceConfig.Workspace.Context, "") + if err != nil { + return fmt.Errorf("read local WSLg authorization: %w", err) + } + if !cfg.ContextOptionBool(pkgconfig.ContextOptionWSLgEnabled) { + return nil + } + if err := r.validateWSLgSupport(options); err != nil { + return err + } + target := wslg.Target{ + Distro: cfg.ContextOption(pkgconfig.ContextOptionWSLgDistro), + User: cfg.ContextOption(pkgconfig.ContextOptionWSLgUser), + } + if err := wslg.ValidateTarget(target); err != nil { + return err + } + if err := r.checkWSLgCollisions(options); err != nil { + return err + } + r.wslgSnapshot, err = wslg.Discover(ctx, target) + return err +} + +func (r *runner) validateWSLgSupport(options provider.CLIOptions) error { + helper, ok := r.driver.(driver.DockerHelperProvider) + if runtime.GOOS != goosWindows || !ok || !r.localDockerWSLgScope(options) { + return wslg.ErrUnsupported + } + dockerHelper, err := helper.DockerHelper() + if err != nil { + return err + } + if dockerHelper.GetRuntime().Name() != docker.RuntimeDocker { + return wslg.ErrUnsupported + } + return nil +} + +func (r *runner) localDockerWSLgScope(options provider.CLIOptions) bool { + return r.workspaceConfig.Agent.Local == pkgconfig.BoolTrue && !options.Platform.Enabled && + (r.workspaceConfig.Agent.Driver == "" || r.workspaceConfig.Agent.Driver == provider.DockerDriver) +} + +func (r *runner) checkWSLgCollisions(options provider.CLIOptions) error { + return wslg.CheckEnvironmentSources(map[string][]string{ + "process environment": os.Environ(), + "--init-env": options.InitEnv, + "provider Docker environment": wslg.Pairs(r.workspaceConfig.Agent.Docker.Env), + }, runtime.GOOS == goosWindows) +} + +type wslgReplay struct { + Target wslg.Target `json:"target"` + Environment map[string]string `json:"environment"` +} + +func (r *runner) wslgReplay() *wslgReplay { + if r.wslgSnapshot == nil { + return nil + } + return &wslgReplay{Target: r.wslgSnapshot.Target(), Environment: r.wslgSnapshot.Environment()} +} + +func validateWSLgReplay(replay *wslgReplay) error { + if replay == nil { + return fmt.Errorf("missing persisted WSLg metadata") + } + if err := wslg.ValidateTarget(replay.Target); err != nil { + return err + } + if replay.Environment[wslg.Display] == "" && replay.Environment[wslg.WaylandDisplay] == "" { + return fmt.Errorf("persisted WSLg metadata has no usable display") + } + return wslg.ValidateEnvironment(replay.Environment) +} + +func readWSLgReplay(details *config.ContainerDetails) (*wslgReplay, error) { + value := details.Config.Labels[wslgSnapshotLabel] + if value == "" { + return nil, nil + } + replay := &wslgReplay{} + if err := decodeWSLgMetadata(value, replay); err != nil { + return nil, fmt.Errorf("invalid persisted WSLg metadata") + } + if err := validateWSLgReplay(replay); err != nil { + return nil, err + } + return replay, nil +} + +func decodeWSLgMetadata(value string, result any) error { + if !utf8.ValidString(value) || !json.Valid([]byte(value)) { + return fmt.Errorf("invalid persisted WSLg/Compose metadata") + } + decoder := json.NewDecoder(strings.NewReader(value)) + decoder.DisallowUnknownFields() + if err := decoder.Decode(result); err != nil { + return fmt.Errorf("invalid persisted WSLg/Compose metadata") + } + return nil +} + +func (r *runner) checkWSLgReuse(details *config.ContainerDetails, recreate bool) error { + if details == nil || recreate { + return nil + } + previous, err := readWSLgReplay(details) + if err != nil { + return err + } + current := r.wslgReplay() + if previous == nil && current == nil { + return nil + } + if replayMatches(previous, current) && + details.State.Status == config.ContainerStatusRunning { + return nil + } + return fmt.Errorf( + "WSLg configuration changed or its container is stopped; " + + "rerun with --recreate to refresh display environment and socket mounts", + ) +} + +// A stopped container keeps display values and socket mounts from creation. +func checkWSLgResume(details *config.ContainerDetails) error { + replay, err := readWSLgReplay(details) + if err != nil { + return err + } + if replay == nil { + return nil + } + return fmt.Errorf( + "WSLg workspace container is stopped; rerun workspace up with --recreate " + + "to refresh display environment and socket mounts before connecting", + ) +} + +// Devsy cannot recreate an attached container, so it carries no WSLg state. +func (r *runner) checkWSLgReuseFor( + devcontainer *config.DevContainerConfig, + details *config.ContainerDetails, + recreate bool, +) error { + if devcontainer != nil && devcontainer.ContainerID != "" { + return nil + } + return r.checkWSLgReuse(details, recreate) +} + +func (r *runner) checkWSLgReuseBeforeInitialize( + ctx context.Context, + devcontainer *config.DevContainerConfig, + options UpOptions, +) error { + // With discovery off this lookup is skipped so ordinary workspaces pay no + // extra Docker call; a revoked label is still rejected by the later check. + if options.Recreate || r.wslgSnapshot == nil { + return nil + } + details, err := r.findOverlayExisting(ctx) + if err != nil { + return err + } + return r.checkWSLgReuseFor(devcontainer, details, options.Recreate) +} + +func replayMatches(previous, current *wslgReplay) bool { + return previous != nil && current != nil && previous.Target == current.Target && + maps.Equal(previous.Environment, current.Environment) +} + +func (r *runner) wslgLabels() (map[string]string, error) { + replay := r.wslgReplay() + if replay == nil { + return nil, nil + } + value, err := json.Marshal(replay) + if err != nil { + return nil, err + } + return map[string]string{wslgSnapshotLabel: string(value)}, nil +} diff --git a/pkg/devcontainer/wslg_test.go b/pkg/devcontainer/wslg_test.go new file mode 100644 index 0000000000..a74c9b315d --- /dev/null +++ b/pkg/devcontainer/wslg_test.go @@ -0,0 +1,341 @@ +package devcontainer + +import ( + "context" + "encoding/json" + "fmt" + "os" + "path/filepath" + "runtime" + "strings" + "testing" + + composetypes "github.com/compose-spec/compose-go/v2/types" + "github.com/devsy-org/devsy/pkg/compose" + pkgconfig "github.com/devsy-org/devsy/pkg/config" + "github.com/devsy-org/devsy/pkg/devcontainer/config" + "github.com/devsy-org/devsy/pkg/provider" + "github.com/devsy-org/devsy/pkg/types" + "github.com/devsy-org/devsy/pkg/wslg" + "github.com/stretchr/testify/suite" + "gopkg.in/yaml.v3" +) + +const ( + wslgTestContext = "wslg-test" + wslgTestBadFlagValue = "yes" + wslgTestExternalID = "external-container" +) + +type WSLgSuite struct{ suite.Suite } + +func TestWSLgSuite(t *testing.T) { suite.Run(t, new(WSLgSuite)) } + +func (s *WSLgSuite) TestSubstitutionIsPerWorkspaceAndDoesNotInjectContainerEnv() { + first, second := newTestRunner(&mockDriver{}), newTestRunner(&mockDriver{}) + first.workspaceConfig.Workspace = &provider.Workspace{ID: "first"} + second.workspaceConfig.Workspace = &provider.Workspace{ID: "second"} + first.wslgSnapshot, second.wslgSnapshot = s.snapshot(":0"), s.snapshot(":1") + raw := &config.DevContainerConfig{} + raw.Image = "${localEnv:DEVSY_WSLG_DISPLAY}" + for _, r := range []*runner{first, second} { + parsed, ctx, err := r.substitute( + provider.CLIOptions{InitEnv: []string{"CUSTOM=override"}}, + raw, + ) + s.Require().NoError(err) + s.Equal(r.wslgSnapshot.Environment()[wslg.Display], parsed.Config.Image) + s.Equal("override", ctx.Env[wslgSubstitutionKey("CUSTOM")]) + s.Empty(parsed.Config.ContainerEnv) + _, ok := ctx.Env[wslgSubstitutionKey(wslg.WaylandDisplay)] + s.False(ok) + } + _, ok := os.LookupEnv(wslg.Display) + s.False(ok) +} + +func (s *WSLgSuite) TestCollisionSources() { + r := newTestRunner(&mockDriver{}) + s.ErrorIs( + r.checkWSLgCollisions(provider.CLIOptions{InitEnv: []string{wslg.Display + "="}}), + wslg.ErrCollision, + ) + r.workspaceConfig.Agent.Docker.Env = map[string]string{wslg.WaylandDisplay: "private"} + err := r.checkWSLgCollisions(provider.CLIOptions{}) + s.ErrorIs(err, wslg.ErrCollision) + s.NotContains(err.Error(), "private") + r.workspaceConfig.Agent.Docker.Env = nil + s.T().Setenv(wslg.RuntimeDir, "private") + err = r.checkWSLgCollisions(provider.CLIOptions{}) + s.ErrorIs(err, wslg.ErrCollision) + s.NotContains(err.Error(), "private") +} + +func (s *WSLgSuite) TestReuseRequiresRecreateForStaleStoppedAndRevoked() { + r := newTestRunner(&mockDriver{}) + r.wslgSnapshot = s.snapshot(":0") + labels, err := r.wslgLabels() + s.Require().NoError(err) + details := &config.ContainerDetails{} + details.Config.Labels = labels + details.State.Status = config.ContainerStatusRunning + s.NoError(r.checkWSLgReuse(details, false)) + details.State.Status = config.ContainerStatusExited + s.ErrorContains(r.checkWSLgReuse(details, false), "--recreate") + s.NoError(r.checkWSLgReuse(details, true)) + details.State.Status = config.ContainerStatusRunning + r.wslgSnapshot = s.snapshot(":1") + s.ErrorContains(r.checkWSLgReuse(details, false), "--recreate") + r.wslgSnapshot = nil + s.ErrorContains(r.checkWSLgReuse(details, false), "--recreate") + details.Config.Labels = nil + s.NoError(r.checkWSLgReuse(details, false)) + r.wslgSnapshot = s.snapshot(":0") + s.ErrorContains(r.checkWSLgReuse(details, false), "--recreate") +} + +func (s *WSLgSuite) TestResumeRejectsStoppedWSLgContainer() { + r := newTestRunner(&mockDriver{}) + r.wslgSnapshot = s.snapshot(":0") + labels, err := r.wslgLabels() + s.Require().NoError(err) + details := &config.ContainerDetails{} + details.Config.Labels = labels + s.ErrorContains(checkWSLgResume(details), "--recreate") + details.Config.Labels = map[string]string{wslgSnapshotLabel: "{"} + s.Error(checkWSLgResume(details)) + details.Config.Labels = nil + s.NoError(checkWSLgResume(details)) +} + +func (s *WSLgSuite) TestReplayKeepsHelperEnvironmentWithoutRecordedValues() { + helper := (&compose.ComposeHelper{}).WithInvocationEnvironment(s.snapshot(":0").Environment()) + s.Same(helper, replayComposeEnvironment(helper, nil)) + s.NotSame(helper, replayComposeEnvironment(helper, map[string]string{wslg.Display: ":1"})) +} + +func (s *WSLgSuite) TestExternalContainerSkipsReuseCheck() { + r := newTestRunner(&mockDriver{}) + r.wslgSnapshot = s.snapshot(":0") + details := &config.ContainerDetails{} + details.State.Status = config.ContainerStatusRunning + parsed := &config.SubstitutedConfig{Config: &config.DevContainerConfig{}} + params := &resolveParams{parsedConfig: parsed, options: UpOptions{}} + err := r.prepareContainerRecreation(context.Background(), details, params) + s.ErrorContains(err, "--recreate") + parsed.Config.ContainerID = wslgTestExternalID + s.NotContains( + fmt.Sprint(r.prepareContainerRecreation(context.Background(), details, params)), + "WSLg", + ) +} + +func (s *WSLgSuite) TestEarlyReuseCheckRejectsStoppedContainerBeforeHook() { + r := newTestRunner(&mockDriver{}) + r.wslgSnapshot = s.snapshot(":0") + labels, err := r.wslgLabels() + s.Require().NoError(err) + details := &config.ContainerDetails{} + details.Config.Labels = labels + details.State.Status = config.ContainerStatusExited + r.driver = &mockDriver{findResult: details} + devcontainer := &config.DevContainerConfig{} + err = r.checkWSLgReuseBeforeInitialize(context.Background(), devcontainer, UpOptions{}) + s.ErrorContains(err, "--recreate") + recreate := UpOptions{} + recreate.Recreate = true + s.NoError(r.checkWSLgReuseBeforeInitialize(context.Background(), devcontainer, recreate)) + devcontainer.ContainerID = wslgTestExternalID + s.NoError(r.checkWSLgReuseBeforeInitialize(context.Background(), devcontainer, UpOptions{})) +} + +func (s *WSLgSuite) TestOverlayCheckExemptsAttachedContainer() { + r := newTestRunner(&mockDriver{}) + r.wslgSnapshot = s.snapshot(":0") + details := &config.ContainerDetails{} + details.State.Status = config.ContainerStatusRunning + r.driver = &mockDriver{findResult: details} + parsed := &config.SubstitutedConfig{Config: &config.DevContainerConfig{}} + err := r.checkOverlayRecreation(context.Background(), parsed, UpOptions{}) + s.ErrorContains(err, "--recreate") + parsed.Config.ContainerID = wslgTestExternalID + s.NoError(r.checkOverlayRecreation(context.Background(), parsed, UpOptions{})) +} + +func (s *WSLgSuite) TestInvocationAcceptsDashPrefixedPaths() { + invocation := composeInvocation{ + Version: 1, + Directory: "project", + Args: []string{"-f", "-dev.yaml", composeTestEnvFlag, "-local.env"}, + } + s.NoError(validateComposeInvocation(invocation)) +} + +func (s *WSLgSuite) TestScopeIgnoresProviderInstallationName() { + r := newTestRunner(&mockDriver{}) + r.workspaceConfig.Agent = provider.ProviderAgentConfig{ + Driver: provider.DockerDriver, + Local: types.StrBool(pkgconfig.BoolTrue), + } + r.workspaceConfig.Workspace = &provider.Workspace{ + Provider: provider.WorkspaceProviderConfig{Name: "my-docker"}, + } + s.True(r.localDockerWSLgScope(provider.CLIOptions{})) + r.workspaceConfig.Agent.Driver = provider.KubernetesDriver + s.False(r.localDockerWSLgScope(provider.CLIOptions{})) +} + +func (s *WSLgSuite) TestV2InvocationLabelRoundTripAndTeardown() { + dir := s.T().TempDir() + base := filepath.Join(dir, "compose.yaml") + override := filepath.Join(dir, "override.yaml") + s.Require(). + NoError(os.WriteFile(base, []byte(`services: + dev: + image: alpine + environment: + DISPLAY: ${DEVSY_WSLG_DISPLAY:?required} +`), 0o600)) + s.Require(). + NoError(os.WriteFile(override, []byte("services:\n dev:\n labels: {}\n"), 0o600)) + r := newTestRunner(&mockDriver{}) + r.wslgSnapshot = s.snapshot(":0$literal$$dollars") + invocation := composeInvocation{ + Version: 2, + Directory: dir, + Args: []string{"-f", base, "-f", override}, + WSLg: r.wslgReplay(), + } + s.Require(). + NoError(recordComposeInvocation(composeInvocationRecord{Path: override, Service: "dev", Invocation: invocation})) + project, err := compose.LoadDockerComposeProjectWithEnv( + context.Background(), + []string{base, override}, + nil, + r.wslgSnapshot.Environment(), + ) + s.Require().NoError(err) + value := project.Services["dev"].Labels[composeInvocationLabel] + var actual composeInvocation + s.Require().NoError(json.Unmarshal([]byte(value), &actual)) + s.Equal(invocation, actual) + details := &config.ContainerDetails{} + details.Config.Labels = map[string]string{ + pkgconfig.ComposeProjectLabel: wslgTestContext, + composeInvocationLabel: value, + } + r.driver = &mockDriver{findResult: details} + // Deliberately clear all discovery state; cleanup uses only recorded input. + r.wslgSnapshot = nil + replay, err := r.composeTeardownArgs(context.Background(), wslgTestContext) + s.Require().NoError(err) + s.Equal(":0$literal$$dollars", replay.WSLgEnv[wslg.Display]) + s.Equal(append([]string{composeProjectDirFlag, dir}, invocation.Args...), replay.Args) +} + +func (s *WSLgSuite) TestCorruptReplayFailsClosed() { + good := composeInvocation{ + Version: 2, + Directory: "project", + Args: []string{"-f", structuralComposeFile}, + WSLg: &wslgReplay{ + Target: wslg.Target{Distro: "Ubuntu", User: "alice"}, + Environment: map[string]string{wslg.Display: ":0"}, + }, + } + s.NoError(validateComposeInvocation(good)) + bad := good + bad.WSLg = nil + s.Error(validateComposeInvocation(bad)) + bad = good + bad.Version = 3 + s.Error(validateComposeInvocation(bad)) + bad = good + bad.Args = []string{"--privileged", wslgTestBadFlagValue} + s.Error(validateComposeInvocation(bad)) + bad = good + bad.WSLg = &wslgReplay{ + Target: good.WSLg.Target, + Environment: map[string]string{"SSH_AUTH_SOCK": "private"}, + } + s.Error(validateComposeInvocation(bad)) + bad = good + bad.WSLg = &wslgReplay{ + Target: good.WSLg.Target, + Environment: map[string]string{wslg.Display: "bad\nvalue"}, + } + s.Error(validateComposeInvocation(bad)) +} + +func (s *WSLgSuite) TestContainerEnvSurvivesComposeInterpolation() { + r := newTestRunner(&mockDriver{}) + r.wslgSnapshot = s.snapshot(":0$literal$$dollars") + env := map[string]string{"DISPLAY": r.wslgSnapshot.Environment()[wslg.Display]} + project := &composetypes.Project{ + Services: composetypes.Services{ + "dev": composetypes.ServiceConfig{ + Image: exampleBaseImage, + Environment: r.composeContainerEnvironment(env), + }, + }, + } + data, err := yaml.Marshal(project) + s.Require().NoError(err) + path := filepath.Join(s.T().TempDir(), "compose.yaml") + s.Require().NoError(os.WriteFile(path, data, 0o600)) + loaded, err := compose.LoadDockerComposeProjectWithEnv( + context.Background(), + []string{path}, + nil, + r.wslgSnapshot.Environment(), + ) + s.Require().NoError(err) + s.Equal(env["DISPLAY"], *loaded.Services["dev"].Environment["DISPLAY"]) + s.Equal(":0$literal$$dollars", env["DISPLAY"], "do not mutate merged configuration") +} + +func (s *WSLgSuite) TestLocalAuthorizationOffAndUnsupported() { + s.T().Setenv(pkgconfig.EnvHome, s.T().TempDir()) + s.T().Setenv(pkgconfig.EnvConfig, "") + s.T().Setenv(wslg.Display, "ordinary-user-value") + r := newTestRunner(&mockDriver{}) + r.workspaceConfig.Workspace = &provider.Workspace{ID: wslgTestContext, Context: wslgTestContext} + cfg, err := pkgconfig.LoadConfig(wslgTestContext, "") + s.Require().NoError(err) + s.Require().NoError(r.prepareWSLg(context.Background(), provider.CLIOptions{})) + s.Nil(r.wslgSnapshot) + raw := &config.DevContainerConfig{} + raw.Image = "${localEnv:DEVSY_WSLG_DISPLAY}" + parsed, _, err := r.substitute(provider.CLIOptions{}, raw) + s.Require().NoError(err) + s.Equal("ordinary-user-value", parsed.Config.Image) + cfg.Current().Options[pkgconfig.ContextOptionWSLgEnabled] = pkgconfig.OptionValue{ + Value: pkgconfig.BoolTrue, + } + s.Require().NoError(pkgconfig.SaveConfig(cfg)) + // The resolved mock driver is unsupported on every OS. The owner opt-in + // must fail before attempting any WSL command or colliding with process env. + s.ErrorIs(r.prepareWSLg(context.Background(), provider.CLIOptions{}), wslg.ErrUnsupported) +} + +func (s *WSLgSuite) TestReplayRejectsTrailingAndUnknownData() { + for _, value := range []string{`{"version":1,"extra":"ignored"}`, `{"version":2} trailing`, string([]byte{0xff})} { + s.Error(decodeWSLgMetadata(value, &composeInvocation{})) + } +} + +func (s *WSLgSuite) snapshot(display string) *wslg.Snapshot { + snap, err := wslg.NewSnapshot( + wslg.Target{Distro: "Ubuntu", User: "alice"}, + map[string]string{wslg.Display: display, wslg.RuntimeDir: ""}, + ) + s.Require().NoError(err) + return snap +} + +func wslgSubstitutionKey(key string) string { + if runtime.GOOS == goosWindows { + return strings.ToLower(key) + } + return key +} diff --git a/pkg/wslg/command.go b/pkg/wslg/command.go new file mode 100644 index 0000000000..098253ecab --- /dev/null +++ b/pkg/wslg/command.go @@ -0,0 +1,65 @@ +package wslg + +import ( + "context" + "errors" + "os" + "os/exec" + "path/filepath" + "strings" + "time" +) + +type commandRunner struct{} + +func (commandRunner) Run(ctx context.Context, path string, args []string) (ProbeResult, error) { + //nolint:gosec // System API resolves the executable; argv is a fixed printenv probe. + cmd := exec.CommandContext(ctx, path, args...) + // WSLENV would translate Windows variables such as DISPLAY into the probe. + cmd.Env = withoutWSLENV(os.Environ()) + // A fixed working directory avoids wsl.exe path translation warnings. + cmd.Dir = filepath.Dir(path) + cmd.WaitDelay = time.Second + stdout, stderr := &boundedOutput{}, &boundedOutput{} + cmd.Stdout, cmd.Stderr = stdout, stderr + err := cmd.Run() + if ctx.Err() != nil { + return ProbeResult{}, ctx.Err() + } + result := ProbeResult{Stdout: stdout.data, Stderr: stderr.data, ExitCode: -1} + if cmd.ProcessState != nil { + result.ExitCode = cmd.ProcessState.ExitCode() + } + if stdout.overflow || stderr.overflow { + return ProbeResult{}, ErrProtocol + } + if _, ok := errors.AsType[*exec.ExitError](err); ok { + return result, nil + } + return result, err +} + +func withoutWSLENV(env []string) []string { + out := make([]string, 0, len(env)) + for _, entry := range env { + key, _, _ := strings.Cut(entry, "=") + if !strings.EqualFold(key, "WSLENV") { + out = append(out, entry) + } + } + return out +} + +type boundedOutput struct { + data []byte + overflow bool +} + +func (b *boundedOutput) Write(p []byte) (int, error) { + remaining := outputLimit - len(b.data) + if len(p) > remaining { + b.overflow = true + } + b.data = append(b.data, p[:min(len(p), remaining)]...) + return len(p), nil +} diff --git a/pkg/wslg/path_other.go b/pkg/wslg/path_other.go new file mode 100644 index 0000000000..c54b35464d --- /dev/null +++ b/pkg/wslg/path_other.go @@ -0,0 +1,5 @@ +//go:build !windows + +package wslg + +func systemWSLPath() (string, error) { return "", ErrUnsupported } diff --git a/pkg/wslg/path_windows.go b/pkg/wslg/path_windows.go new file mode 100644 index 0000000000..b11f45e66a --- /dev/null +++ b/pkg/wslg/path_windows.go @@ -0,0 +1,24 @@ +package wslg + +import ( + "os" + "path/filepath" + + "golang.org/x/sys/windows" +) + +func systemWSLPath() (string, error) { + directory, err := windows.GetSystemDirectory() + if err != nil { + return "", ErrExecutable + } + path := filepath.Join(directory, "wsl.exe") + if !filepath.IsAbs(path) { + return "", ErrExecutable + } + info, err := os.Stat(path) + if err != nil || info.IsDir() { + return "", ErrExecutable + } + return path, nil +} diff --git a/pkg/wslg/probe_windows_test.go b/pkg/wslg/probe_windows_test.go new file mode 100644 index 0000000000..4fb9609602 --- /dev/null +++ b/pkg/wslg/probe_windows_test.go @@ -0,0 +1,74 @@ +package wslg + +import ( + "context" + "os" + "path/filepath" + "testing" + "time" + + "github.com/stretchr/testify/require" + "golang.org/x/sys/windows" +) + +// CI supplies a real WSL distro/user. Ordinary Windows unit runs need no WSL. +func TestWSLgNativeProbe(t *testing.T) { + distro := os.Getenv("DEVSY_WSLG_TEST_DISTRO") + if distro == "" { + t.Skip("requires the Windows WSL CI fixture") + } + target := Target{Distro: distro, User: os.Getenv("DEVSY_WSLG_TEST_USER")} + ctx, cancel := context.WithTimeout(context.Background(), 45*time.Second) + defer cancel() + path, err := systemWSLPath() + require.NoError(t, err) + dir, err := windows.GetSystemDirectory() + require.NoError(t, err) + require.Equal(t, filepath.Join(dir, "wsl.exe"), path) + // Verify the GNU printenv missing-key convention against the real distro. + result, err := (commandRunner{}).Run( + ctx, + path, + []string{ + "--distribution", + target.Distro, + "--user", + target.User, + "--exec", + "/usr/bin/printenv", + "DEVSY_WSLG_TEST_UNSET_1464", + }, + ) + require.NoError(t, err) + require.Equal(t, 1, result.ExitCode) + require.Empty(t, result.Stdout) + require.Empty(t, result.Stderr) + snapshot, err := Discover(ctx, target) + require.NoError( + t, + err, + "fixed noninteractive WSLg discovery must work; this runner cannot prove visible Windows windows", + ) + require.NotEmpty(t, snapshot.Environment()) + // Cross-check against an independent printenv through the same runner. + direct, err := (commandRunner{}).Run( + ctx, + path, + []string{ + "--distribution", + target.Distro, + "--user", + target.User, + "--exec", + "/usr/bin/printenv", + "DISPLAY", + }, + ) + require.NoError(t, err) + want, _, err := parseResult(direct) + require.NoError(t, err) + require.Equal(t, want, snapshot.Environment()[Display]) + for key := range snapshot.Environment() { + t.Logf("discovered %s", key) + } +} diff --git a/pkg/wslg/wslg.go b/pkg/wslg/wslg.go new file mode 100644 index 0000000000..a089870820 --- /dev/null +++ b/pkg/wslg/wslg.go @@ -0,0 +1,301 @@ +// Package wslg discovers an explicitly selected WSL user's display connection +// values. It never imports a shell environment or grants access to GUI sockets. +package wslg + +import ( + "context" + "errors" + "fmt" + "maps" + "slices" + "strings" + "time" + "unicode" + "unicode/utf8" +) + +const ( + Display = "DEVSY_WSLG_DISPLAY" + WaylandDisplay = "DEVSY_WSLG_WAYLAND_DISPLAY" + RuntimeDir = "DEVSY_WSLG_XDG_RUNTIME_DIR" + outputLimit = 4096 + discoveryTimeout = 30 * time.Second +) + +var ( + ErrUnsupported = errors.New( + "WSLg discovery requires native Windows and a local Docker runtime", + ) + ErrInvalidTarget = errors.New("WSLg discovery requires an explicit non-root WSL distro/user") + ErrExecutable = errors.New("WSLg discovery cannot locate the Windows system wsl.exe") + ErrProtocol = errors.New( + "WSLg probe failed; verify the selected distro/user and /usr/bin/printenv", + ) + ErrUnavailable = errors.New( + "WSLg has no usable DISPLAY or WAYLAND_DISPLAY for the selected user; " + + "check that the distribution is running and WSLg is enabled", + ) + ErrCollision = errors.New("reserved WSLg environment assignment") +) + +type Target struct { + Distro string `json:"distro"` + User string `json:"user"` +} + +// Snapshot contains only present keys; an empty string is distinct from absence. +// Accessors return copies so an invocation cannot mutate another's environment. +type Snapshot struct { + target Target + env map[string]string +} + +func NewSnapshot(target Target, env map[string]string) (*Snapshot, error) { + if err := ValidateTarget(target); err != nil { + return nil, err + } + if err := ValidateEnvironment(env); err != nil { + return nil, err + } + // Non-nil even when empty so collision checks keyed on a snapshot always run. + return &Snapshot{target: target, env: mapsCloneNonNil(env)}, nil +} + +func (s *Snapshot) Environment() map[string]string { + if s == nil { + return nil + } + return mapsCloneNonNil(s.env) +} + +func mapsCloneNonNil(env map[string]string) map[string]string { + clone := make(map[string]string, len(env)) + maps.Copy(clone, env) + return clone +} + +func (s *Snapshot) Target() Target { return s.target } + +func ValidateTarget(target Target) error { + for _, value := range []string{target.Distro, target.User} { + if !validTargetName(value) { + return ErrInvalidTarget + } + } + if target.User == "root" || target.User == "0" { + return ErrInvalidTarget + } + return nil +} + +func validTargetName(value string) bool { + if value == "" || len(value) > 256 || strings.HasPrefix(value, "-") || + !utf8.ValidString(value) { + return false + } + for _, ch := range value { + if unicode.IsControl(ch) || unicode.IsSpace(ch) { + return false + } + } + return true +} + +func Reserved(key string, windows bool) bool { + if windows { + key = strings.ToUpper(key) + } + return key == Display || key == WaylandDisplay || key == RuntimeDir +} + +// Display values reach logs and Compose documents, so no control characters. +func hasControl(value string) bool { + return strings.ContainsFunc(value, func(r rune) bool { return r < 0x20 || r == 0x7f }) +} + +func ValidateEnvironment(env map[string]string) error { + for key, value := range env { + if !Reserved(key, false) || len(value) > outputLimit-1 || !utf8.ValidString(value) || + hasControl(value) { + return fmt.Errorf("invalid WSLg replay environment") + } + } + return nil +} + +func CheckCollisions(source string, env []string, windows bool) error { + for _, entry := range env { + key, _, ok := strings.Cut(entry, "=") + if ok && Reserved(key, windows) { + return fmt.Errorf( + "%w: %s in %s; remove the assignment or disable WSLG_ENABLED", + ErrCollision, + key, + source, + ) + } + } + return nil +} + +// CheckEnvironmentSources rejects assignments before provider construction can +// log its effective environment or start a runtime. +func CheckEnvironmentSources(sources map[string][]string, windows bool) error { + for _, source := range slices.Sorted(maps.Keys(sources)) { + env := sources[source] + if err := CheckCollisions(source, env, windows); err != nil { + return err + } + if err := checkComposeEnvFiles(env, windows); err != nil { + return err + } + } + return nil +} + +func checkComposeEnvFiles(env []string, windows bool) error { + for _, entry := range env { + key, value, _ := strings.Cut(entry, "=") + if windows { + key = strings.ToUpper(key) + } + if key == "COMPOSE_ENV_FILES" && value != "" { + return fmt.Errorf("WSLg discovery does not support COMPOSE_ENV_FILES; " + + "use project .env files or disable WSLG_ENABLED") + } + } + return nil +} + +func Pairs(env map[string]string) []string { + keys := slices.Sorted(maps.Keys(env)) + pairs := make([]string, 0, len(keys)) + for _, key := range keys { + pairs = append(pairs, key+"="+env[key]) + } + return pairs +} + +// Overlay replaces the reserved entries, including Windows case variants, once. +// Ordinary environment precedence remains the caller's responsibility. +func Overlay(base []string, env map[string]string, windows bool) []string { + out := make([]string, 0, len(base)+len(env)) + for _, entry := range base { + key, _, _ := strings.Cut(entry, "=") + if !Reserved(key, windows) { + out = append(out, entry) + } + } + return append(out, Pairs(env)...) +} + +type ProbeResult struct { + Stdout []byte + Stderr []byte + ExitCode int +} + +type Runner interface { + Run(context.Context, string, []string) (ProbeResult, error) +} + +func Discover(ctx context.Context, target Target) (*Snapshot, error) { + if err := ValidateTarget(target); err != nil { + return nil, err + } + path, err := systemWSLPath() + if err != nil { + return nil, err + } + return Capture(ctx, target, path, commandRunner{}) +} + +// Capture exposes the bounded probe for tests; production always resolves the +// trusted executable using the Windows system API in Discover. +func Capture(ctx context.Context, target Target, path string, runner Runner) (*Snapshot, error) { + if err := ValidateTarget(target); err != nil { + return nil, err + } + ctx, cancel := context.WithTimeout(ctx, discoveryTimeout) + defer cancel() + env := map[string]string{} + probe := displayProbe{path: path, target: target, runner: runner} + for _, key := range []string{"DISPLAY", "WAYLAND_DISPLAY", "XDG_RUNTIME_DIR"} { + value, present, err := probe.value(ctx, key) + if err != nil { + return nil, err + } + if present { + env["DEVSY_WSLG_"+key] = value + } + } + if env[Display] == "" && env[WaylandDisplay] == "" { + return nil, ErrUnavailable + } + return NewSnapshot(target, env) +} + +type displayProbe struct { + path string + target Target + runner Runner +} + +func (p displayProbe) value(ctx context.Context, key string) (string, bool, error) { + if err := ctx.Err(); err != nil { + return "", false, err + } + result, err := p.runner.Run( + ctx, + p.path, + []string{ + "--distribution", + p.target.Distro, + "--user", + p.target.User, + "--exec", + "/usr/bin/printenv", + key, + }, + ) + if ctx.Err() != nil { + return "", false, ctx.Err() + } + if err != nil { + return "", false, fmt.Errorf("%w (%s)", ErrProtocol, key) + } + value, present, err := parseResult(result) + if err != nil { + return "", false, fmt.Errorf("%w (%s)", err, key) + } + return value, present, nil +} + +// wsl.exe warnings, such as a mirrored-proxy notice, go to stderr and do not +// affect printenv. A value is read from stdout only, so stderr is tolerated when +// the probe succeeded. Silence is required to read "absent" from exit code 1, +// otherwise a wsl.exe failure would look like a missing variable. +func parseResult(result ProbeResult) (string, bool, error) { + if len(result.Stdout) > outputLimit { + return "", false, ErrProtocol + } + if result.ExitCode == 1 && len(result.Stdout) == 0 && len(result.Stderr) == 0 { + return "", false, nil + } + if result.ExitCode != 0 { + return "", false, ErrProtocol + } + value, err := parseValue(result.Stdout) + return value, err == nil, err +} + +func parseValue(stdout []byte) (string, error) { + if !utf8.Valid(stdout) || !strings.HasSuffix(string(stdout), "\n") { + return "", ErrProtocol + } + value := strings.TrimSuffix(strings.TrimSuffix(string(stdout), "\n"), "\r") + if hasControl(value) { + return "", ErrProtocol + } + return value, nil +} diff --git a/pkg/wslg/wslg_test.go b/pkg/wslg/wslg_test.go new file mode 100644 index 0000000000..7a04037937 --- /dev/null +++ b/pkg/wslg/wslg_test.go @@ -0,0 +1,239 @@ +package wslg + +import ( + "context" + "errors" + "io" + "os" + "strings" + "testing" + "time" + + "github.com/stretchr/testify/suite" +) + +const ( + testDistro = "Ubuntu" + testUser = "alice" + testOrdinaryDisplay = "DISPLAY=:9" + testProcessHelper = "-test.run=^TestWSLgProcessHelper$" +) + +type WSLgSuite struct{ suite.Suite } + +func TestWSLgSuite(t *testing.T) { suite.Run(t, new(WSLgSuite)) } + +type fakeRunner struct { + run func(context.Context, string, []string) (ProbeResult, error) +} + +func (r fakeRunner) Run(ctx context.Context, path string, args []string) (ProbeResult, error) { + return r.run(ctx, path, args) +} + +func (s *WSLgSuite) TestCaptureAllowlistPresenceAndImmutability() { + calls := 0 + target := Target{Distro: "Ubuntu-24.04", User: testUser} + snapshot, err := Capture( + context.Background(), + target, + "trusted-wsl", + fakeRunner{run: func(_ context.Context, path string, args []string) (ProbeResult, error) { + s.Equal("trusted-wsl", path) + names := []string{"DISPLAY", "WAYLAND_DISPLAY", "XDG_RUNTIME_DIR"} + s.Equal( + []string{ + "--distribution", + target.Distro, + "--user", + target.User, + "--exec", + "/usr/bin/printenv", + names[calls], + }, + args, + ) + results := []ProbeResult{ + {Stdout: []byte(":0\r\n")}, + {Stdout: []byte("\n")}, + {ExitCode: 1}, + } + result := results[calls] + calls++ + return result, nil + }}, + ) + s.Require().NoError(err) + s.Equal(3, calls) + s.Equal(target, snapshot.Target()) + s.Equal(map[string]string{Display: ":0", WaylandDisplay: ""}, snapshot.Environment()) + env := snapshot.Environment() + env[Display] = "changed" + s.Equal(":0", snapshot.Environment()[Display]) +} + +func (s *WSLgSuite) TestEmptySnapshotEnvironmentIsNonNil() { + snapshot, err := NewSnapshot(Target{Distro: testDistro, User: testUser}, nil) + s.Require().NoError(err) + s.NotNil(snapshot.Environment()) + s.Empty(snapshot.Environment()) + s.Error(ValidateEnvironment(map[string]string{Display: "a\x1bb"})) +} + +func (s *WSLgSuite) TestProbeEnvironmentDropsWSLENV() { + env := withoutWSLENV([]string{"A=1", "WSLENV=DISPLAY/u", "wslenv=x", "DISPLAY=:3"}) + s.Equal([]string{"A=1", "DISPLAY=:3"}, env) +} + +func (s *WSLgSuite) TestInvalidTargetsNeverRun() { + for _, target := range []Target{ + {}, + {"-Ubuntu", testUser}, + {testDistro, "root"}, + {testDistro, "0"}, + {"Ubuntu x", testUser}, + {testDistro, "--help"}, + {testDistro, "alice\n"}, + {testDistro, strings.Repeat("a", 257)}, + } { + _, err := Capture( + context.Background(), + target, + "wsl", + fakeRunner{run: func(context.Context, string, []string) (ProbeResult, error) { + s.Fail("must not run") + return ProbeResult{}, nil + }}, + ) + s.ErrorIs(err, ErrInvalidTarget) + } +} + +func (s *WSLgSuite) TestStrictProtocol() { + for _, result := range []ProbeResult{ + {Stdout: []byte("private")}, + {Stdout: []byte("private\n\n")}, + {Stdout: []byte("a\x00b\n")}, + {Stdout: []byte{0xff, '\n'}}, + {Stdout: []byte("a\rb\n")}, + {Stdout: []byte("a\tb\n")}, + {Stdout: []byte("a\x1bb\n")}, + {Stdout: []byte("a\x7fb\n")}, + {ExitCode: 1, Stderr: []byte("private")}, + {ExitCode: 2, Stdout: []byte("a\n"), Stderr: []byte("private")}, + {ExitCode: 1, Stdout: []byte("private\n")}, + {ExitCode: 2}, + {Stdout: []byte(strings.Repeat("a", outputLimit) + "\n")}, + } { + _, _, err := parseResult(result) + s.ErrorIs(err, ErrProtocol) + s.NotContains(err.Error(), "private") + } + for _, output := range []string{"\n", "\r\n", "a$${literal}\n"} { + _, present, err := parseResult(ProbeResult{Stdout: []byte(output)}) + s.NoError(err) + s.True(present) + } + _, present, err := parseResult(ProbeResult{ExitCode: 1}) + s.NoError(err) + s.False(present) + value, present, err := parseResult( + ProbeResult{Stdout: []byte(":0\n"), Stderr: []byte("wsl: proxy notice")}, + ) + s.NoError(err) + s.True(present) + s.Equal(":0", value) +} + +func (s *WSLgSuite) TestCancellationAndUnavailable() { + target := Target{testDistro, testUser} + ctx, cancel := context.WithCancel(context.Background()) + cancel() + _, err := Capture(ctx, target, "wsl", fakeRunner{}) + s.ErrorIs(err, context.Canceled) + for _, result := range []ProbeResult{{ExitCode: 1}, {Stdout: []byte("\n")}} { + _, err = Capture( + context.Background(), + target, + "wsl", + fakeRunner{ + run: func(context.Context, string, []string) (ProbeResult, error) { return result, nil }, + }, + ) + s.ErrorIs(err, ErrUnavailable) + } + ctx, cancel = context.WithTimeout(context.Background(), time.Millisecond) + defer cancel() + _, err = Capture( + ctx, + target, + "wsl", + fakeRunner{run: func(ctx context.Context, _ string, _ []string) (ProbeResult, error) { + <-ctx.Done() + return ProbeResult{}, ctx.Err() + }}, + ) + s.ErrorIs(err, context.DeadlineExceeded) +} + +func (s *WSLgSuite) TestNamespaceAndOverlay() { + s.ErrorIs(CheckCollisions("process", []string{"devsy_wslg_display="}, true), ErrCollision) + s.NoError(CheckCollisions("process", []string{"devsy_wslg_display="}, false)) + s.NoError(CheckCollisions("process", []string{testOrdinaryDisplay}, true)) + env := Overlay( + []string{testOrdinaryDisplay, "devsy_wslg_display=old", Display + "=duplicate"}, + map[string]string{Display: ":0", RuntimeDir: ""}, + true, + ) + s.Equal([]string{testOrdinaryDisplay, Display + "=:0", RuntimeDir + "="}, env) + s.Error(ValidateEnvironment(map[string]string{"PULSE_SERVER": "secret"})) + s.Error(ValidateEnvironment(map[string]string{Display: "x\n"})) +} + +func (s *WSLgSuite) TestSubprocessBoundsAndCancellation() { + path, err := os.Executable() + s.Require().NoError(err) + result, err := (commandRunner{}).Run( + context.Background(), + path, + []string{testProcessHelper, "--", "large"}, + ) + s.ErrorIs(err, ErrProtocol) + s.Empty(result.Stdout) + ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond) + defer cancel() + _, err = (commandRunner{}).Run( + ctx, + path, + []string{testProcessHelper, "--", "wait"}, + ) + s.ErrorIs(err, context.DeadlineExceeded) + result, err = (commandRunner{}).Run( + context.Background(), + path, + []string{testProcessHelper, "--", "missing"}, + ) + s.NoError(err) + s.Equal(1, result.ExitCode) + s.Empty(result.Stdout) +} + +func TestWSLgProcessHelper(t *testing.T) { + if len(os.Args) < 2 || os.Args[len(os.Args)-2] != "--" { + return + } + switch os.Args[len(os.Args)-1] { + case "large": + _, err := io.WriteString(os.Stdout, strings.Repeat("a", outputLimit+1)) + if err != nil { + os.Exit(2) + } + case "wait": + time.Sleep(time.Minute) + case "missing": + os.Exit(1) + default: + t.Fatal(errors.New("invalid helper mode")) + } + os.Exit(0) +} diff --git a/sites/docs-devsy-sh/content/docs/tutorials/docker-provider-via-wsl.mdx b/sites/docs-devsy-sh/content/docs/tutorials/docker-provider-via-wsl.mdx index 9ec5c39d43..b88a32e575 100644 --- a/sites/docs-devsy-sh/content/docs/tutorials/docker-provider-via-wsl.mdx +++ b/sites/docs-devsy-sh/content/docs/tutorials/docker-provider-via-wsl.mdx @@ -84,13 +84,102 @@ When `DOCKER_HOST` is not a local socket, Devsy converts Windows drive paths in Create the workspace. Devsy adds an SSH config entry named `.devsy`: ```bash -devsy up +devsy workspace up ``` In VS Code or VSCodium with the [Open Remote - SSH](https://marketplace.visualstudio.com/items?itemName=jeanp413.open-remote-ssh) extension, choose **Open Folder in Remote...** and select that host. Devsy tunnels the session into the dev container, so no jump host setup is needed. -The tunnel reuses your local SSH keys and agent. If the editor log shows `write EPIPE`, run `devsy up` with `DEVSY_DEBUG=true`. The real cause, such as the WSL SSH server not running or an untrusted host key, is otherwise hidden behind that generic error. +The tunnel reuses your local SSH keys and agent. If the editor log shows `write EPIPE`, run `devsy workspace up` with `DEVSY_DEBUG=true`. The real cause, such as the WSL SSH server not running or an untrusted host key, is otherwise hidden behind that generic error. ## Next steps See [Create a Workspace](../developing-in-workspaces/create-a-workspace.mdx). + +## Experimental WSLg display discovery + +Windows Devsy can discover display connection values from an explicitly selected WSL2 distribution and non-root user. This is opt-in and requires a local Docker provider (the built-in `docker` provider or a named copy of it) with Docker Engine in that distribution, as configured above. Docker Desktop, Podman, remote providers and Devsy running inside WSL are outside this feature's scope. The Docker endpoint must reach the same distribution: its name or an SSH address alone does not establish that identity. + +First check that a GUI application works directly in your distribution and that these commands from PowerShell return its display values. Replace the distribution and username: + +```powershell +wsl.exe --distribution Ubuntu-24.04 --user alice --exec /usr/bin/printenv DISPLAY +wsl.exe --distribution Ubuntu-24.04 --user alice --exec /usr/bin/printenv WAYLAND_DISPLAY +wsl.exe --distribution Ubuntu-24.04 --user alice --exec /usr/bin/printenv XDG_RUNTIME_DIR +``` + +Devsy uses this fixed noninteractive probe, with a 30-second total deadline. It does not start a login shell or read shell profiles. If these commands cannot read the values used by your GUI application, this discovery method cannot support that setup. + +Enable discovery in the owner-controlled Devsy context, using the same context as your workspace: + +```powershell +devsy context set -o WSLG_ENABLED=true -o WSLG_DISTRO=Ubuntu-24.04 -o WSLG_USER=alice +``` + +The experimental v1 substitution interface exposes only: + +| WSL value | Devsy substitution / Compose interpolation key | +| --- | --- | +| `DISPLAY` | `DEVSY_WSLG_DISPLAY` | +| `WAYLAND_DISPLAY` | `DEVSY_WSLG_WAYLAND_DISPLAY` | +| `XDG_RUNTIME_DIR` | `DEVSY_WSLG_XDG_RUNTIME_DIR` | + +Missing values stay absent, and present empty values stay empty. Discovery sets no container environment and adds no mounts. While discovery is enabled, Compose `containerEnv` values are written literally, so a `$` in them is not interpolated by Compose. Explicitly map the desired values in your project. Audio, GPU, session bus, SSH sockets and `WAYLAND_SOCKET` file descriptors are not imported. + +These names are reserved while discovery is enabled. Remove assignments to them from your Windows environment, `--init-env`, provider Docker environment and Compose interpolation `.env` files. Even empty assignments, or differently cased Windows names, are rejected. Ordinary `DISPLAY` remains user-controlled. Service `env_file` entries are container environment, separate from interpolation files. The separate `COMPOSE_ENV_FILES` environment override is unsupported while discovery is enabled; use the project `.env` files Devsy passes explicitly. + +### X11 configuration mechanics + +The following examples show the environment and mount configuration. They require an image with an X11 client, a working WSLg server and a daemon-visible `/tmp/.X11-unix/X0` socket. Hosted CI checks environment transport and socket access; a visible Windows window still needs acceptance testing on your machine. See Microsoft's [WSLg container guidance](https://github.com/microsoft/wslg/blob/main/samples/container/Containers.md) for the underlying socket requirements. + +For an image or Dockerfile devcontainer, map the discovered display and pass an explicit daemon-side bind using Docker `runArgs`: + +```json +{ + "image": "your-image-with-an-x11-client", + "containerEnv": { + "DISPLAY": "${localEnv:DEVSY_WSLG_DISPLAY}" + }, + "runArgs": [ + "--mount", + "type=bind,source=/tmp/.X11-unix,target=/tmp/.X11-unix,readonly" + ] +} +``` + +`runArgs` sends this explicit Linux source directly to Docker's strict `--mount` validation. Devsy's general `mounts` property still checks bind sources on the Windows client; use the explicit Docker argument for this daemon-only socket path. A missing source fails instead of creating a directory. + +For Compose, the namespaced values are available when Devsy loads the original Compose files and when the Compose executable processes them: + +```yaml +services: + dev: + image: your-image-with-an-x11-client + command: sleep infinity + environment: + DISPLAY: "${DEVSY_WSLG_DISPLAY:?Enable WSLg discovery for this context}" + volumes: + - type: bind + source: /tmp/.X11-unix + target: /tmp/.X11-unix + read_only: true + bind: + create_host_path: false +``` + +A read-only Unix socket mount still allows communication with its server. Trust projects that receive access to your GUI session. Devsy does not change X11 authorization, socket permissions, user IDs or host networking. `remoteEnv` only affects later remote sessions; it cannot repair original Compose interpolation or configure the container entrypoint. + +### Wayland and lifecycle + +Wayland values can be referenced using the same explicit mapping, but `XDG_RUNTIME_DIR` is a **host** path with user ownership and permission requirements. Do not copy it blindly into the container or mount the whole host `/run/user` directory. Map only the daemon-visible Wayland socket into a container runtime directory owned by the intended user, or use an absolute socket path with a client that supports it. A native Wayland GUI recipe requires separate runtime acceptance; the X11 example does not prove it. + +Each up/recreate/build captures fresh display values. Already running containers can be reused only when the recorded distribution, user and values match. Stopped WSLg containers, changed values, newly enabled discovery and opting out all require explicit `devsy workspace up --recreate`. After a WSL restart, use `--recreate` even if the strings match: socket identities may have changed. + +Stop and delete never probe WSL. Compose containers record an allowlisted v2 invocation label containing the distribution/user and the three present display values, plus the original Compose paths needed for cleanup. Image containers carry the same display identity marker. These labels are visible to anyone who can inspect the Docker daemon; they contain host connection metadata, not credentials. Retained workspace build and lifecycle logs also record any command output, so a hook or build step that prints `DEVSY_WSLG_*` values stores them there. Cleanup still needs a reachable Docker daemon and, for Compose, the original project files. + +Disable discovery with: + +```powershell +devsy context set -o WSLG_ENABLED=false +``` + +Recreate existing WSLg workspaces after changing this setting. Disabled discovery preserves ordinary environment resolution and does not invoke WSL.