116 lines
7.3 KiB
Markdown
116 lines
7.3 KiB
Markdown
# M1 spikes (docs/WINDOWS_PORT.md §13)
|
|
|
|
Programs that answer questions the port is currently *guessing* at. They are checked in and
|
|
runnable on purpose: a spike whose answer nobody can reproduce six months later is a rumour.
|
|
|
|
They are deliberately **not** in `windows/Nucleic.sln`. The solution's broker contract tests must
|
|
keep running on any machine against `FakeWslc`; these need the `Microsoft.WSL.Containers` preview
|
|
NuGet and a real WSL stack, so they are built by path.
|
|
|
|
---
|
|
|
|
## `WslcApiDump` — what does the wslc API actually look like?
|
|
|
|
**Status: it has served its original purpose (docs/WINDOWS_PORT.md §13.1).** The real API is
|
|
known, and it was obtained without a Windows machine at all — the package is public, so the
|
|
`.nupkg` was downloaded, its projection assembly extracted, and its metadata read with
|
|
`MetadataLoadContext`. What this tool is *for* has therefore changed: its assumption list now
|
|
describes the surface actually observed in 2.9.3, so running it says **what the next package
|
|
version moved**, not what we guessed wrong.
|
|
|
|
**Why it is still reflection.** Same reason as before: a typed check fails to compile on the
|
|
first rename and reports one problem, where this reports all of them at once. That property is
|
|
worth keeping for a preview API whose next version can break anything.
|
|
|
|
Two facts it discovered that anything referencing this package needs:
|
|
|
|
- the assembly is **`wslcsdkcs.dll`**, not `Microsoft.WSL.Containers.dll` — loading it by package
|
|
name fails;
|
|
- the only published version is **2.9.3**, targeting `net8.0-windows10.0.19041.0`. The
|
|
`0.1.0-preview.1` pin this repo carried could never have restored.
|
|
|
|
```powershell
|
|
cd windows/spikes/WslcApiDump
|
|
dotnet run # dump the API + check every facade assumption
|
|
dotnet run -- --probe # + GetMissingComponents / GetVersion
|
|
dotnet run -- --session # + create a session, then a SECOND one with the same name
|
|
dotnet run -- --all-types # include the ABI/marshalling plumbing in the dump
|
|
```
|
|
|
|
**If it reports missing components** (`VirtualMachinePlatform`, `WslPackage`), the machine cannot
|
|
run wslc yet: `wsl --install`, reboot for the Virtual Machine Platform feature, and run again.
|
|
Everything that reaches the service fails with `REGDB_E_CLASSNOTREG` (0x80040154) until then, and
|
|
the tool says so rather than emitting a string of unexplained COM errors. `--session` is skipped
|
|
in that state instead of failing.
|
|
|
|
Note that the assumption check reads the **`Microsoft.WSL.Containers`** namespace only. That is
|
|
correctness, not tidiness: a C#/WinRT projection also exports `ABI.Microsoft.WSL.Containers.*`
|
|
marshalling types with the *same short names*, and matching on short name alone checks every
|
|
member against the marshalling struct — which reported 42 false MISSINGs, with `CreateMarshaler`
|
|
helpfully offered as the nearest name.
|
|
|
|
It writes the full public object model to `wslc-api-dump.txt` (`--out` to relocate) and prints an
|
|
`ok` / `MISSING` line per assumption, each with *why that member matters* and a nearest-name hint.
|
|
It exits 0 even when assumptions fail — a mismatch is the product, not an error. Only a genuinely
|
|
broken run (the assembly won't load) exits non-zero.
|
|
|
|
Every path in it has been exercised against a stand-in assembly carrying the observed 2.9.3 type
|
|
and member names — including the `ABI.` shadow types and a service that reports missing components
|
|
and throws `0x80040154` — so a failure on your machine is a finding about wslc, not about this
|
|
tool.
|
|
|
|
**What to send back:** the console output, and `wslc-api-dump.txt` if anything is MISSING —
|
|
which now means the package moved under us, not that we guessed wrong.
|
|
|
|
### Why `--session` earns its risk
|
|
|
|
`--session` creates a real wslc session named `nucleic-spike` under
|
|
`%LOCALAPPDATA%\Nucleic\spike\wslc`, starts it, and then **creates a second one with the same
|
|
name**. That second construction is the whole point, and it is the last open question D13 turns
|
|
on: the compat SDK exposes a `Session` *constructor* and no attach, so does constructing over an
|
|
existing name re-adopt it, or refuse?
|
|
|
|
- **Refused** (expect `WSLC_E_SESSION_RESERVED`, `0x80040607`) — D13's premise is confirmed on
|
|
hardware rather than inferred from an IDL, and session reattach genuinely requires
|
|
`IWSLCSessionManager::OpenSessionByName` on the internal interface.
|
|
- **Constructed** — the compat surface may re-adopt by name, and the session half of §2.3 reattach
|
|
may not need the internal interface at all. Check `wslc container ps` for the first session's
|
|
containers before believing it.
|
|
|
|
It leaves the session running on purpose, because that is the other half of the same question:
|
|
broker supervision assumes wslc state is **service-backed**, so a crashed `nucleic-brokerd` can
|
|
re-adopt rather than orphaning containers. If `wslc session ls` still shows `nucleic-spike` after
|
|
this process exits, that holds. Tear it down with `wslc` when you're done.
|
|
|
|
The gateway address is *not* what this probe is for any more — §13.1 established that no API
|
|
surfaces one, and D13 moves the control plane to hvsocket via `IWSLCVirtualMachine::GetId`.
|
|
|
|
### The three answers that change the design
|
|
|
|
Most mismatches are a one-line edit in `WslcFacade.cs` — that is exactly what the `IWslc` seam is
|
|
for, and nothing above it should move. These three are different:
|
|
|
|
| Finding | Consequence |
|
|
| --- | --- |
|
|
| No container enumeration, stats, pty or attach in the SDK | **Settled by D13.** `wslcsdk.dll` wraps `WSLCCompat.idl` (the stable SDK surface), which genuinely lacks them; they all exist on `wslc.idl`, the service-internal COM interface `wslc.exe` calls — `ListContainers`, `Stats`, `ResizeTty`, `OpenContainer`/`Attach`, `OpenSessionByName`, and `IWSLCVirtualMachine::GetId`. The broker binds both surfaces; no CLI. |
|
|
| No create-or-attach on `Session` | **Answered:** `IWSLCSessionManager::OpenSessionByName` / `EnterSession` / `ListSessions` on the internal interface. §2.3 reattach has its mechanism. |
|
|
| No gateway address anywhere on the API | **Skip TCP:** `IWSLCVirtualMachine::GetId` returns the VM GUID, so §5's AF_HYPERV/AF_VSOCK path (true vsock parity with macOS) should become primary at M1 (b). Gateway TCP stays as fallback, its address from `GetAdaptersAddresses` over `vEthernet (WSL)`. |
|
|
| No uid on `ProcessSettings` | Recoverable, and already planned for: exec wraps argv in `setpriv`/`su agent -c`. Interceptors and nash don't care about the numeric uid (§3.2). |
|
|
|
|
---
|
|
|
|
## Not yet written
|
|
|
|
- **`WslcSpike`** — the typed happy path: session → GHCR pull of `naros-agent` → container with an
|
|
NTFS `ContainerVolume` → `exec git status` in the bind-mounted worktree → stdio round-trip →
|
|
SIGTERM, plus the 9P latency numbers §15 wants (`git status` and `npm install` on a real repo,
|
|
mounted vs. in-VM). Deliberately held back until `WslcApiDump` has run: written now, against
|
|
guessed names, it would not compile, and fixing it blind is the mistake this whole approach
|
|
exists to avoid.
|
|
- **`HvSocketSpike`** — M1 (b), and now the *primary* control-plane spike rather than the
|
|
fallback one (D13): bind an AF_HYPERV listener on the VM GUID from
|
|
`IWSLCVirtualMachine::GetId` and dial AF_VSOCK from inside a wslc container. If vsock
|
|
traverses the container's namespaces, the Windows control plane gets true parity with macOS
|
|
and §5's firewall/NAT variance stops mattering. Measure gateway-TCP reachability in the same
|
|
run so the fallback stays evidenced.
|