106 lines
7.0 KiB
C#
106 lines
7.0 KiB
C#
namespace WslcApiDump;
|
|
|
|
/// <summary>
|
|
/// Every member <c>NucleicBroker/Wslc/WslcFacade.cs</c> calls on the preview
|
|
/// <c>Microsoft.WSL.Containers</c> API, as plain strings.
|
|
///
|
|
/// The facade was written from Microsoft's documentation without a machine to run it on
|
|
/// (docs/WINDOWS_PORT.md §1.5), so each line here is a *claim* — and this spike's job is to say,
|
|
/// for each one, whether the shipped assembly agrees. Strings rather than typed references is the
|
|
/// entire trick: a typed spike that names <c>Session.CreateOrOpen</c> fails to COMPILE if that
|
|
/// method has a different name, which teaches us nothing. Reflection turns every wrong guess into
|
|
/// a printed line instead of a build error, so one run produces the complete worklist.
|
|
///
|
|
/// Keep in lockstep with WslcFacade.cs. A member that stops being used should leave this list;
|
|
/// a newly-used member should join it, so the next run of this tool still covers the real surface.
|
|
/// </summary>
|
|
internal static class FacadeAssumptions
|
|
{
|
|
internal sealed record Assumption(string Type, string Member, Kind MemberKind, string Why);
|
|
|
|
internal enum Kind { Method, Property, Event, Constructor, EnumValue, Type }
|
|
|
|
internal static readonly Assumption[] All =
|
|
[
|
|
// ---- Service entry point: onboarding (§8 step 2) ----
|
|
new("WslcService", "GetServiceVersion", Kind.Method,
|
|
"hello capabilities — hostd degrades across preview→GA churn on this string"),
|
|
new("WslcService", "GetMissingComponents", Kind.Method,
|
|
"components.missing RPC; drives the guided-install onboarding page"),
|
|
new("WslcService", "InstallComponentsAsync", Kind.Method,
|
|
"components.install RPC"),
|
|
new("ComponentFlags", "None", Kind.EnumValue,
|
|
"the 'nothing missing' sentinel the facade filters on"),
|
|
|
|
// ---- Session: one per channel, hosts every container (§3.2) ----
|
|
new("SessionSettings", ".ctor", Kind.Constructor,
|
|
"SessionSettings(name, dataDir) — the two-arg shape the facade assumes"),
|
|
new("SessionSettings", "CpuCount", Kind.Property, "session.ensure cpu"),
|
|
new("SessionSettings", "MemoryMB", Kind.Property,
|
|
"session.ensure memoryMB; §3.2 notes a resize needs a sandbox restart"),
|
|
new("Session", "CreateOrOpen", Kind.Method,
|
|
"THE create-or-attach primitive. If this is absent, broker reattach after a crash "
|
|
+ "(§2.3) has no mechanism and the whole supervision design changes"),
|
|
new("Session", "Terminate", Kind.Method, "session.terminate RPC"),
|
|
new("Session", "SessionTerminationHandler", Kind.Property,
|
|
"session.down notification → hostd's reconcile sweep"),
|
|
new("Session", "HostGatewayAddress", Kind.Property,
|
|
"THE control-plane address (§5). ensureRunning returns it to the Swift engine and "
|
|
+ "control-bridge.js dials it. If this member does not exist, §5's primary transport "
|
|
+ "needs another source (query the vNIC) or the hvsocket fallback gets promoted"),
|
|
|
|
// ---- Images ----
|
|
new("Session", "PullImageAsync", Kind.Method, "image.pull RPC (naros-agent from GHCR)"),
|
|
new("PullImageOptions", ".ctor", Kind.Constructor, "PullImageOptions(reference)"),
|
|
new("PullImageOptions", "Credentials", Kind.Property, "GHCR auth (registryAuth)"),
|
|
new("PullImageOptions", "Progress", Kind.Event,
|
|
"image.pullProgress → the existing controlDownloadProgress UI surface"),
|
|
new("RegistryCredentials", ".ctor", Kind.Constructor, "RegistryCredentials(user, password)"),
|
|
new("Session", "GetImages", Kind.Method, "image.list / image.inspect"),
|
|
new("Session", "DeleteImage", Kind.Method, "image.delete"),
|
|
|
|
// ---- Containers ----
|
|
new("Session", "CreateContainer", Kind.Method, "container.create"),
|
|
new("Session", "GetContainers", Kind.Method, "container.list; reattach re-enumeration"),
|
|
new("ContainerSettings", ".ctor", Kind.Constructor, "ContainerSettings(image)"),
|
|
new("ContainerSettings", "Name", Kind.Property, "channel-suffixed container naming"),
|
|
new("ContainerSettings", "Hostname", Kind.Property, "container.create hostname"),
|
|
new("ContainerSettings", "NetworkingMode", Kind.Property,
|
|
"NAT vs mirrored (§5 item 4) — determines how the guest reaches the host"),
|
|
new("ContainerSettings", "Volumes", Kind.Property, "the NTFS worktree bind mount (D8)"),
|
|
new("ContainerSettings", "InitProcess", Kind.Property, "naros-init as PID 1 (docs/NAROS.md)"),
|
|
new("ContainerVolume", ".ctor", Kind.Constructor,
|
|
"ContainerVolume(hostPath, guestPath, readOnly) — the 3-arg shape"),
|
|
new("ContainerNetworkingMode", "", Kind.Type, "enum parsed from the RPC's networkingMode"),
|
|
new("Container", "Start", Kind.Method, "container.start"),
|
|
new("Container", "Stop", Kind.Method, "container.stop(signal, grace)"),
|
|
new("Container", "Delete", Kind.Method, "container.delete"),
|
|
new("Container", "State", Kind.Property, "container.state → running/stopped/absent"),
|
|
new("Container", "GetStatistics", Kind.Method,
|
|
"container.stats → ContainerResourceSample; the Swift engine folds deltas from it"),
|
|
new("Container", "RunProcess", Kind.Method, "proc.exec — the agent's own exec path"),
|
|
new("ContainerState", "Running", Kind.EnumValue, "the one state the facade tests by name"),
|
|
new("DeleteContainerFlags", "Force", Kind.EnumValue, "container.delete force"),
|
|
|
|
// ---- Processes: the agent stdio path (§3.2 WslcProcessHandle) ----
|
|
new("ProcessSettings", "CmdLine", Kind.Property, "argv"),
|
|
new("ProcessSettings", "Environment", Kind.Property, "env"),
|
|
new("ProcessSettings", "WorkingDirectory", Kind.Property, "cwd"),
|
|
new("ProcessSettings", "OutputMode", Kind.Property, "event-mode stdio, not polling"),
|
|
new("ProcessSettings", "Terminal", Kind.Property, "tty for the Terminal panel (§7)"),
|
|
new("ProcessSettings", "UserId", Kind.Property,
|
|
"runAsUID 501 (§3.2). If absent, exec falls back to a setpriv/su wrapper argv — "
|
|
+ "interceptors and nash don't care about the numeric uid, so this is recoverable"),
|
|
new("ProcessSettings", "GroupId", Kind.Property, "runAsGID"),
|
|
new("ProcessOutputMode", "Event", Kind.EnumValue,
|
|
"the mode that makes stdio push-based; polling would change the whole broker design"),
|
|
new("Signal", "", Kind.Type, "the enum Stop/Signal take; the RPC carries POSIX ints"),
|
|
new("Process", "OutputReceived", Kind.Event, "→ proc.stdout / proc.stderr notifications"),
|
|
new("Process", "Exited", Kind.Event, "→ proc.exit; must never overtake output (OutboundWriter)"),
|
|
new("Process", "WriteStdin", Kind.Method, "proc.stdin (NDJSON to the agent)"),
|
|
new("Process", "CloseStdin", Kind.Method, "proc.closeStdin"),
|
|
new("Process", "Signal", Kind.Method, "proc.signal — the agent's real POSIX Stop path"),
|
|
new("Process", "ResizeTerminal", Kind.Method, "proc.resize (tty mode)"),
|
|
];
|
|
}
|