Add Uid/Gid/Mode/Fixed driver options to WSLC VHD volumes; expose via SDK

[benhillis]

Summary

Adds POSIX Uid/Gid/Mode and pre-allocated Fixed driver options to the WSLC named-volume vhd driver, and plumbs them through the public C SDK and the WinRT projection.

Today, containers running as a non-root user cannot write to their own persistent volumes — mkfs.ext4 leaves the root owned by root:root with mode 0755, and the vhd driver only accepted SizeBytes. The new options let the SDK consumer create a volume that is immediately usable by the in-container user.

Fixed lets workloads that need predictable I/O pre-allocate the VHD instead of growing it dynamically.

Driver options (named volumes)

Option	Type	Notes
SizeBytes	uint64 (decimal)	required; >0
Fixed	bool (true/false/1/0)	optional; defaults to false
Uid	uint32 (decimal)	optional; must be paired with Gid
Gid	uint32 (decimal)	optional; must be paired with Uid
Mode	uint32 (octal)	optional; 1..07777

All option parsing now goes through a new shared OptionParser helper (Required<T>/Optional<T>/OptionalBool/RejectUnknown) with errno-capture, end-pointer validation, leading-sign rejection, and consumed-key tracking. The Open path uses the same parser so persisted metadata is validated identically on reload.

C SDK (wslcsdk.h / wslcsdk.dll)

typedef enum WslcVhdRequirementsFlags {
    WSLC_VHD_REQ_FLAG_NONE  = 0,
    WSLC_VHD_REQ_FLAG_OWNER = 1,
    WSLC_VHD_REQ_FLAG_MODE  = 2,
} WslcVhdRequirementsFlags;

typedef struct WslcVhdRequirements {
    PCSTR    name;
    uint64_t sizeBytes;
    WslcVhdType type;
    WslcVhdRequirementsFlags flags;
    uint32_t uid;
    uint32_t gid;
    uint32_t mode;
} WslcVhdRequirements;

WslcCreateSessionVhdVolume:

• honors WSLC_VHD_TYPE_FIXED (was previously E_NOTIMPL)
• dynamically builds the underlying WSLCDriverOption[] based on the flag bits
• rejects unknown type values, unknown flag bits, and mode == 0 with E_INVALIDARG so future additions cannot be silently fail-open and obvious foot-guns are caught client-side
• formats mode as octal (std::format("{:o}", mode)) so the service-side base-8 parser round-trips it correctly

WslcSetSessionSettingsVhd does not plumb owner/mode/fixed through the session rootfs VHD path and now rejects flags != NONE with E_INVALIDARG instead of silently ignoring those fields.

Important

ABI break: WSLC_SESSION_OPTIONS_SIZE bumps 80 → 96 to match the wider embedded WslcVhdRequirements. Callers of wslcsdk.lib/wslcsdk.dll must recompile against the new header.

Caller usage

WslcVhdRequirements vhd = {0};
vhd.name      = "data";
vhd.sizeBytes = 64ULL << 20;
vhd.type      = WSLC_VHD_TYPE_FIXED;
vhd.flags     = WSLC_VHD_REQ_FLAG_OWNER | WSLC_VHD_REQ_FLAG_MODE;
vhd.uid       = 65534;
vhd.gid       = 65534;
vhd.mode      = 0750;
WslcCreateSessionVhdVolume(session, &vhd, &errorMsg);

WinRT projection (Microsoft.WSL.Containers)

runtimeclass VhdRequirements {
    VhdRequirements(String name, UInt64 sizeInBytes, VhdType type);
    String  Name        { get; };
    UInt64  SizeInBytes { get; };
    VhdType Type        { get; };

    void SetOwner(UInt32 uid, UInt32 gid);
    void SetMode(UInt32 mode);
}

Pair-based SetOwner avoids the half-set foot-gun that per-property setters would create. Default-constructed VhdRequirements (or any path that does not call the new setters) gets flags = NONE = old behavior.

var req = new VhdRequirements("data", 64UL << 20, VhdType.Fixed);
req.SetOwner(65534, 65534);
req.SetMode(0x1E8); // 0o750

The WinRT projection has no test infrastructure in the repo (the existing Name/SizeInBytes/Type projection has never had tests either). Behavior is fully covered at the C SDK layer that the projection delegates to.

Tests

• WSLCTests.cpp
  • NamedVolumeVhdOptionsParseTest — SizeBytes presence/range/base, unknown-key rejection (Bogus=...), sign rejection
  • NamedVolumesVhdOwnership — chown/chmod end-to-end
  • NamedVolumesVhdFixed — asserts on-disk file_size >= requested
• WslcSdkTests.cpp
  • Invalid type → E_INVALIDARG
  • Fixed positive (size verification on disk)
  • OWNER | MODE positive (uid=65534, gid=65534, mode=0750)
  • Mode out-of-range (> 07777) → E_INVALIDARG
  • Mode == 0 → E_INVALIDARG
  • Unknown flag bit → E_INVALIDARG
  • flags=NONE with non-zero uid/gid silently ignored

Validation status

• cmake --build clean (wslservice, wslcsession, wslcsdk, wslcsdkwinrt, wsltests)
• FormatSource.ps1 -ModifiedOnly $true — clang-format reports no changes
• bin\x64\Debug\test.bat /name:WSLCTests::*NamedVolumeVhd* — needs Administrator
• bin\x64\Debug\test.bat /name:WSLCTests::*NamedVolumesVhd* — needs Administrator
• SDK functional tests under WslcSdkTests — needs Administrator
• python tools/devops/validate-localization.py — local Python is MS Store stub
• python tools/devops/validate-copyright-headers.py — local Python is MS Store stub

Marking as draft until the admin-elevated test runs and python validators land.

[Copilot]

Pull request overview

Adds support for additional vhd named-volume driver options (POSIX Uid/Gid/Mode and Fixed allocation) and exposes them through the public WSLC C SDK and WinRT projection so SDK callers can create volumes usable by non-root container users and optionally pre-allocate VHD space.

Changes:

• Added a shared OptionParser utility and updated the VHD volume driver to parse/validate SizeBytes, Fixed, Uid/Gid, and Mode, applying ownership/permissions at volume creation time.
• Extended the C SDK WslcVhdRequirements contract (new flags + fields) and updated WslcCreateSessionVhdVolume / WslcSetSessionSettingsVhd behavior accordingly.
• Added/updated Windows tests for driver-option parsing and SDK behavior, plus a new localized error string for invalid volume options.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
test/windows/WSLCTests.cpp	Expands VHD named-volume option parsing tests; adds end-to-end ownership/mode and fixed-allocation coverage.
test/windows/WslcSdkTests.cpp	Updates SDK tests for fixed VHD support, new owner/mode flags, and validation behavior.
src/windows/wslcsession/WSLCVhdVolume.cpp	Implements parsing/validation for new VHD driver options and applies chown/chmod during volume creation; uses shared parser.
src/windows/wslcsession/OptionParser.h	Introduces typed driver-option parsing interface (templates + consumed-key tracking).
src/windows/wslcsession/OptionParser.cpp	Implements lookup, bool parsing, unknown-option rejection, and localized error throwing for OptionParser.
src/windows/wslcsession/CMakeLists.txt	Wires new OptionParser sources into the wslcsession build.
src/windows/WslcSDK/wslcsdk.h	Extends public C SDK types (WslcVhdRequirementsFlags, larger WslcVhdRequirements, updated session options size).
src/windows/WslcSDK/wslcsdk.cpp	Updates WslcCreateSessionVhdVolume to emit new driver options and WslcSetSessionSettingsVhd to reject unsupported flags.
src/windows/WslcSDK/winrt/wslcsdk.idl	Extends WinRT VhdRequirements projection with SetOwner/SetMode.
src/windows/WslcSDK/winrt/VhdRequirements.h	Adds WinRT wrapper method declarations for owner/mode setters.
src/windows/WslcSDK/winrt/VhdRequirements.cpp	Implements WinRT owner/mode setters by setting C SDK struct fields and flags.
localization/strings/en-US/Resources.resw	Adds localized MessageWslcInvalidVolumeOption string used for consistent option-validation errors.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 7 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.