wsl

Documentation

Overview

Package wsl lets a Windows-native `dejima` client drive a `dejimad` running inside a WSL2 distro.

Windows can't host Dejima: dejimad needs a Unix host with Docker (see scripts/setup.sh, which exits on anything but Darwin/Linux, and internal/service, which only knows launchd + systemd). WSL2 *is* such a host — a real Linux kernel with a real Docker — so a Windows user can run the whole stack locally after all, with the daemon one virtualization boundary away.

The transport is deliberately the cheapest thing that preserves the security model: we shell out to `wsl.exe -d <distro> -- socat STDIO UNIX-CONNECT:…` and wrap that process's stdio as a net.Conn. dejimad needs no new listener, no TCP bind, and no relaxation of the tailnet pin; its 0600 Unix socket remains the only operator surface, reachable exactly by whoever can already run commands as that user inside the distro.

A connection target for this path is spelled `wsl://<distro>` and is stored in a client profile like any other host.

Index

• Constants
• Variables
• func Available() bool
• func Dial(ctx context.Context, distro string) (net.Conn, error)
• func DialTimeout() time.Duration
• func Distro(host string) string
• func Host(distro string) string
• func IsHost(host string) bool
• func Run(ctx context.Context, distro, script string) (string, error)
• func RunExe(ctx context.Context, args ...string) (string, error)
• func Supported() bool
• type Distribution
  • func List(ctx context.Context) ([]Distribution, error)
• type Report
  • func Probe(ctx context.Context, distro string) (Report, error)
  • func (r Report) Ready() bool

Constants

const DefaultDistro = "dejima"

DefaultDistro is the distro name `dejima wsl setup` creates and that the first-run flow offers. Named for the project so it's obvious in `wsl -l -v` and can't be confused with a distro the user keeps for other work.

const Scheme = "wsl://"

Scheme prefixes a WSL connection target: "wsl://dejima".

Variables

var ErrUnsupported = errors.New("wsl:// targets work only on Windows (WSL interop); use a host:port address here")

ErrUnsupported is returned when a `wsl://` target is used off Windows.

Functions

func Available

func Available() bool

Available reports whether WSL interop is usable at all: Windows, with wsl.exe on PATH.

func Dial

func Dial(ctx context.Context, distro string) (net.Conn, error)

Dial opens a connection to dejimad's Unix socket inside distro by piping through `wsl.exe … socat`. The returned conn owns the subprocess and kills it on Close.

ctx bounds the *handshake* (spawning wsl.exe), not the connection's lifetime: http.Transport pools connections past the request whose context triggered the dial, so binding the process to that context would kill live pooled conns.

func DialTimeout

func DialTimeout() time.Duration

DialTimeout is the handshake budget callers should use when building a transport for this path.

func Distro

func Distro(host string) string

Distro extracts the distro name from a `wsl://<distro>` host, or "" if host isn't a WSL target. A bare "wsl://" yields DefaultDistro so the shorthand works.

func Host

func Host(distro string) string

Host renders a distro name as a connection target.

func IsHost

func IsHost(host string) bool

IsHost reports whether a connection host names a WSL distro rather than a TCP address.

func Run

func Run(ctx context.Context, distro, script string) (string, error)

Run is run() exported for the setup flow, which needs to execute provisioning steps inside the distro and show their output.

func RunExe

func RunExe(ctx context.Context, args ...string) (string, error)

RunExe invokes wsl.exe with *management* arguments (--install, --set-version, …) rather than a command inside a distro. It returns the combined output even on failure so callers can classify the error (e.g. an old wsl.exe that lacks a flag), and streams nothing — these operations are slow but quiet.

func Supported

func Supported() bool

Supported reports whether this platform can reach a WSL distro at all. WSL interop exists only on Windows; everywhere else a `wsl://` target is a mistake worth naming rather than a dial to attempt.

Types

type Distribution

type Distribution struct {
	Name    string
	State   string // "Running" / "Stopped"
	Version int    // 1 or 2; only 2 has a real kernel + Docker
	Default bool
}

Distribution is one entry from `wsl.exe -l -v`.

func List

func List(ctx context.Context) ([]Distribution, error)

List enumerates installed distros. An empty list with no error means WSL is installed but has no distro yet — the state a fresh Windows box is in after `wsl --install` reboots.

type Report

type Report struct {
	Distro    string
	Exists    bool
	Version   int
	Running   bool
	HasSocat  bool
	HasDocker bool // docker CLI present AND the engine answers
	HasDejima bool // dejimad binary installed
	SocketUp  bool // ~/.dejima/dejimad.sock exists
}

Report is a health read of one distro as a Dejima host.

func Probe

func Probe(ctx context.Context, distro string) (Report, error)

Probe inspects a distro without changing anything. Each check is a single `sh -c` inside the distro; a distro that isn't running will be started by WSL on the first one (that's expected and is why setup is idempotent).

func (Report) Ready

func (r Report) Ready() bool

Ready reports whether this distro can serve as a working local host.