Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .config/dotnet-tools.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,14 @@
"rollForward": false
},
"dotnet-inspect": {
"version": "0.27.0",
"version": "0.28.0",
"commands": [
"dotnet-inspect"
],
"rollForward": false
},
"purview.build": {
"version": "0.9.0",
"version": "0.9.2",
"commands": [
"purview-build"
],
Expand Down
2 changes: 1 addition & 1 deletion .editorconfig
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Purview.BuildSdk 2.0.0 - managed file, do not edit
# Purview.BuildSdk 2.2.0 - managed file, do not edit
#
# This file is written by Purview.BuildSdk and is replaced whenever the SDK version changes. The version
# on the first line is how the SDK recognises a file it owns: a .editorconfig without that marker is
Expand Down
7 changes: 6 additions & 1 deletion .github/workflows/pr.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,15 @@ on:
# `ready_for_review` is not one of the default activity types, so a draft PR would never
# re-evaluate the required build gate once it is marked ready for review.
types: [opened, synchronize, reopened, ready_for_review]
# Every merge to main is built and tested too, so main's own status reflects what was merged rather
# than the last PR head. This never publishes: releases still come only from release/** (release.yml).
push:
branches: [main]

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
# A newer push to a PR supersedes the older run; on main every merge gets its own complete run.
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
build:
Expand Down
33 changes: 19 additions & 14 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,20 +131,22 @@ whenever a target framework, a backend package or the `buildTransitive` assets c
dropped): `Purview.Containers.Core` (abstractions) and the service modules target **`net10.0` and
`net11.0`** on any platform. `Purview.Containers.Wsl` is **multi-target**: `net10.0`/`net11.0` (portable
facades) and `net10.0-windows10.0.19041.0`/`net11.0-windows10.0.19041.0` (the WSLC implementations).
Purview.BuildSdk's `Current` target-framework set supplies the `net10.0;net11.0` list to the library
subtree, while `src/Directory.Build.props` pins that set to `net11.0-windows10.0.19041.0` for
`src/tests` so the WSLC tests bind the implementation; `Wsl.csproj` adds the Windows
builds with a platform-identifier condition (never a literal TFM). The Docker integration projects
`src/Directory.Build.props` selects Purview.BuildSdk's `Supported` target-framework set
(`PurviewTargetFrameworkSet=Supported`, `net10.0;net11.0` in BuildSdk 2.2.0) for every project that
declares no target of its own, and pins that set to `net11.0-windows10.0.19041.0` for `src/tests` so
the WSLC tests bind the implementation. `Wsl.csproj` derives its four targets from the same set (each
supported framework plus its `-windows10.0.19041.0` build) and selects files with a
platform-identifier condition (never a literal TFM). The Docker integration projects
declare `net10.0` directly so they run on Linux **and** keep the lowest supported framework under test.
The contract, the failures that enforce it and the CI workarounds are documented in
[Consumer Requirements](docs/wiki/Consumer-Requirements.md); update that page whenever a target
framework, the `buildTransitive` defaults, the payload layout or the `PCC0001`/`PCC0002` guards change.
- The `net11.0` library builds are compiled with `runtime-async=on` (`PurviewRuntimeAsync=false` opts out):
Purview.BuildSdk applies it to every `net11.0`+ target together with the C# 15
`updated-memory-safety-rules` tier (`MemorySafetyRules=2`), so the repository does not repeat either
switch. The runtime manages suspension instead of compiler-generated state machines, which lowers async
overhead and makes live stack traces name the real methods. `Wsl.UnitTests/BuildFeatureTests.cs` guards
it. The `net10.0` builds keep the classic state machines. Because `closed` hierarchies require
- The `net11.0` builds are compiled with `runtime-async=on` and the C# 15
`updated-memory-safety-rules` tier. Purview.BuildSdk 2.2.0 makes both **opt-in**, so
`src/Directory.Build.props` sets `PurviewRuntimeAsync=true` and `MemorySafetyRules=2` explicitly; do not
remove them. The runtime manages suspension instead of compiler-generated state machines, which lowers
async overhead and makes live stack traces name the real methods. `Wsl.UnitTests/BuildFeatureTests.cs`
guards both. The `net10.0` builds keep the classic state machines. Because `closed` hierarchies require
`System.Runtime.CompilerServices.IsClosedTypeAttribute` and C# unions require `UnionAttribute` (both
.NET 11 runtime types), neither is used: no public hierarchy here is closed anyway — `WaitStrategy`,
`ContainerException` and the backend interfaces are documented extension points.
Expand All @@ -162,8 +164,9 @@ whenever a target framework, a backend package or the `buildTransitive` assets c
tests) registers explicitly instead — `WslcTest.EnsureBackendRegistered()`.
- `src/Directory.Build.props` sets `EnableWindowsTargeting=true` because the shared CI agent is
`ubuntu-latest`; removing it fails the pipeline with `NETSDK1100`.
- The project is **experimental**: keep the experimental notice in `README.md`, `docs/wiki/Home.md` and
the package READMEs, and keep versions on a `-prerelease.N` suffix.
- Versions stay on a `-prerelease.N` suffix until the stable 1.0.0 release, which includes the WSL
Containers backend. The docs, README and package READMEs must not carry experimental or preview
notices.

## Module rules

Expand Down Expand Up @@ -254,8 +257,10 @@ Commit messages follow Conventional Commits enforced by the `commit-msg` lefthoo
## Versioning and releases

- `package.json` is the authoritative release and package version. Do not diverge project versions by hand.
- `.github/workflows/pr.yml` builds and tests pull requests through the shared
`purview-dev/build/.github/workflows/purview-build.yml`, with pack and validation enabled.
- `.github/workflows/pr.yml` builds and tests pull requests **and every push to `main`** through the
shared `purview-dev/build/.github/workflows/purview-build.yml`, with pack and validation enabled (plus
the Docker and WSLC contract jobs). A push to `main` never publishes; superseded PR runs are
cancelled, `main` runs are not.
- `.github/workflows/release.yml` runs the shared release pipeline with `release-mode: NuGet` on a push to a
`release/**` branch (or a manual dispatch), **not** on a push to `main`. Cut a release by merging the
version bump into `main`, then pushing a `release/v…` branch named after the version from it (for
Expand Down
36 changes: 18 additions & 18 deletions Directory.Packages.props
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
<PropertyGroup>
<MicrosoftWSLContainersVersion>3.0.5</MicrosoftWSLContainersVersion>
<WindowsSdkRefPackageVersion>10.0.26100.80</WindowsSdkRefPackageVersion>
<TUnitVersion>1.76.0</TUnitVersion>
<TUnitVersion>1.87.0</TUnitVersion>
</PropertyGroup>

<ItemGroup Label="Transitive Pinning">
Expand All @@ -38,20 +38,20 @@
.NET 10 servicing line on purpose: the .NET 8/.NET 9 lines are no longer supported, and a
component declares the lowest band a consumer on the oldest supported framework can take.
-->
<PackageVersion Include="System.Security.Cryptography.Pkcs" Version="10.0.15" />
<!--<PackageVersion Include="System.Security.Cryptography.Pkcs" Version="10.0.15" />-->
</ItemGroup>
<ItemGroup>
<PackageVersion Include="Aspire.Hosting" Version="13.6.5" />
<PackageVersion Include="Aspire.Hosting" Version="17.0.0" />
<PackageVersion Include="Microsoft.WSL.Containers" Version="$(MicrosoftWSLContainersVersion)" />
<PackageVersion Include="Testcontainers" Version="4.16.0" />
<PackageVersion Include="Testcontainers" Version="4.17.0" />
<!--
Shipped by every package (not PrivateAssets), so its version is the floor every consumer
inherits. 10.0.0 is the .NET 10 GA release of the extension - the lowest that ships for the
oldest framework these packages target - rather than the newest 10.x release.
inherits. 11.0.0 still ships a net10.0 asset (binding the 10.0.x Microsoft.Extensions
servicing line), so raising the floor does not raise the .NET 10 requirement.
-->
<PackageVersion Include="Microsoft.Extensions.Telemetry.Abstractions" Version="10.0.0" />
<PackageVersion Include="Microsoft.SourceLink.GitHub" Version="10.0.402" />
<PackageVersion Include="Purview.Telemetry.SourceGenerator" Version="5.0.5" />
<PackageVersion Include="Microsoft.Extensions.Telemetry.Abstractions" Version="11.0.0" />
<PackageVersion Include="Microsoft.SourceLink.GitHub" Version="11.0.100" />
<PackageVersion Include="Purview.Telemetry.SourceGenerator" Version="6.0.1" />
<PackageVersion Include="TUnit" Version="$(TUnitVersion)" />
<PackageVersion Include="TUnit.Core" Version="$(TUnitVersion)" />
<PackageVersion Include="TUnit.Mocks" Version="$(TUnitVersion)" />
Expand All @@ -62,21 +62,21 @@
package is licensed under the Microsoft Testing Platform Tools terms, which permit use in
OSI-approved open-source projects; it never ships in a Purview package.
-->
<PackageVersion Include="Microsoft.Testing.Extensions.Retry" Version="2.5.1" />
<PackageVersion Include="Purview.Skills.Testing" Version="1.2.0" />
<PackageVersion Include="Microsoft.Testing.Extensions.Retry" Version="2.5.3" />
<PackageVersion Include="Purview.Skills.Testing" Version="2.2.0" />
<PackageVersion Include="Bogus" Version="35.6.5" />
<PackageVersion Include="Azure.Core" Version="1.63.0" />
<PackageVersion Include="Azure.Security.KeyVault.Certificates" Version="4.9.2" />
<PackageVersion Include="Azure.Core" Version="1.65.0" />
<PackageVersion Include="Azure.Security.KeyVault.Certificates" Version="4.10.0" />
<PackageVersion Include="Azure.Security.KeyVault.Keys" Version="4.10.2" />
<PackageVersion Include="Azure.Security.KeyVault.Secrets" Version="4.11.2" />
<PackageVersion Include="Azure.Security.KeyVault.Secrets" Version="4.12.0" />
<!-- Test-only: the Azurite and Service Bus emulator suites prove authenticated client operations. -->
<PackageVersion Include="Azure.Messaging.ServiceBus" Version="7.21.0" />
<PackageVersion Include="Azure.Storage.Blobs" Version="12.30.1" />
<PackageVersion Include="Npgsql" Version="10.0.3" />
<PackageVersion Include="Microsoft.Data.SqlClient" Version="7.1.1" />
<PackageVersion Include="StackExchange.Redis" Version="3.4.5" />
<PackageVersion Include="Microsoft.Data.SqlClient" Version="7.1.2" />
<PackageVersion Include="StackExchange.Redis" Version="3.4.35" />
<PackageVersion Include="RabbitMQ.Client" Version="7.2.2" />
<PackageVersion Include="NATS.Client.Core" Version="3.3.1" />
<PackageVersion Include="MySqlConnector" Version="2.6.2" />
<PackageVersion Include="NATS.Client.Core" Version="3.4.0" />
<PackageVersion Include="MySqlConnector" Version="3.0.0" />
</ItemGroup>
</Project>
27 changes: 11 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,21 +34,16 @@ Testcontainers' `WithCleanUp`: containers are removed by default, `.WithCleanUp(
for inspection, and `.WithAutoRemove()` is opted into separately. See
[Capabilities and Cancellation](docs/wiki/Backend-Capabilities.md) for APIs, ownership and limits.

> **Experimental.** This project is an experiment in running throwaway containers through Microsoft
> WSL Containers. The public API, defaults and packaging rules can change between prereleases, and
> there is no production support guarantee. Pin the exact package version you build against, and read
> [Consumer Requirements](docs/wiki/Consumer-Requirements.md) before adopting it.

> **Status: preview.** Backend-neutral abstractions, two backends (WSL Containers and Docker), wait
> strategies, the `Image`/`Tag` parser, registry auth, observability, hardening, and **nine service
> modules** (PostgreSQL, Redis, SQL Server, RabbitMQ, Azurite, NATS, MySQL, Azure Key Vault Emulator, Azure Service Bus Emulator). On WSLC, **images are shared
> by default** (`StorageMode.Shared`): sessions reuse a stable image store
> (`%LOCALAPPDATA%\Purview\WslContainers\images`) so images are pulled once, not per session;
> `StorageMode.PerSession` provides isolation. Move the store with `PURVIEW_CONTAINERS_STORAGE_PATH` or
> `WslContainerRuntimeOptions.StoragePath`. Named volumes are retained by default; set
> `PURVIEW_CONTAINERS_CLEAN_VOLUMES=true` (or `ContainerCleanup.CleanUpVolumesOnExit`) to delete the
> volumes the library created when the process or session ends. Runnable samples live in
> `samples/getting-started`.
**Features.** Backend-neutral abstractions, two backends (WSL Containers and Docker), wait
strategies, the `Image`/`Tag` parser, registry auth, observability, hardening, and **nine service
modules** (PostgreSQL, Redis, SQL Server, RabbitMQ, Azurite, NATS, MySQL, Azure Key Vault Emulator, Azure
Service Bus Emulator). On WSLC, **images are shared by default** (`StorageMode.Shared`): sessions reuse a
stable image store (`%LOCALAPPDATA%\Purview\WslContainers\images`) so images are pulled once, not per
session; `StorageMode.PerSession` provides isolation. Move the store with
`PURVIEW_CONTAINERS_STORAGE_PATH` or `WslContainerRuntimeOptions.StoragePath`. Named volumes are retained
by default; set `PURVIEW_CONTAINERS_CLEAN_VOLUMES=true` (or `ContainerCleanup.CleanUpVolumesOnExit`) to
delete the volumes the library created when the process or session ends. Runnable samples live in
`samples/getting-started`.

**Documentation:** [Containers documentation](https://purview.dev/docs/containers/)

Expand All @@ -60,7 +55,7 @@ for inspection, and `.WithAutoRemove()` is opted into separately. See
referencing the umbrella package, Testcontainers or WSLC. It verifies native paths, running WSL
translations and explicit shared-remote mappings against the daemon using two-way file markers.
`Purview.Containers.Aspire` adds opt-in `builder.AddContainerEnvironment()` integration for any
Aspire AppHost. Both target `net10.0` and `net11.0`; the adapter requires Aspire 13.6.5 or later.
Aspire AppHost. Both target `net10.0` and `net11.0`; the adapter requires Aspire 17.0.0 or later.
These are separate from the existing Docker backend's automatic WSL2 path handling.
Docker Engine inside a WSL distribution is not Microsoft WSL Containers.
See the [environment package guide](src/src/Environment/Sdk/README.md) and
Expand Down
10 changes: 6 additions & 4 deletions docs/wiki/Architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,16 +53,18 @@ Microsoft types (`Session`, `Container`, `Process`, `ContainerSettings`, …) ar
## Target frameworks

Every package ships `net10.0` and `net11.0` assets. **.NET 8 and .NET 9 are dropped**; the contract is in
[Consumer Requirements](Consumer-Requirements.md). Purview.BuildSdk's `Current` target-framework set
supplies that pair; the repository does not hand-maintain it.
[Consumer Requirements](Consumer-Requirements.md). Purview.BuildSdk's `Supported` target-framework set
(selected in `src/Directory.Build.props`) supplies that pair; the repository does not hand-maintain it,
and the WSL backend derives its Windows builds from the same set.

- `net10.0` is the floor. A consumer that has not moved to .NET 11 keeps the classic compiler-generated
async state machines and the .NET 10 library surface.
- `net11.0` is compiled with `runtime-async=on` and the C# 15 updated memory-safety rules
(`MemorySafetyRules=2`). The runtime manages suspension and resumption instead of compiler-generated
state machines, which lowers async overhead and makes live stack traces (profiler, `new StackTrace()`,
debugger) name the real methods. `PurviewRuntimeAsync=false` opts out for a local experiment;
`Wsl.UnitTests/BuildFeatureTests.cs` guards that the shipped default is on.
debugger) name the real methods. Purview.BuildSdk 2.2.0 makes both features opt-in, so
`src/Directory.Build.props` enables them (`PurviewRuntimeAsync=true`, `MemorySafetyRules=2`);
`Wsl.UnitTests/BuildFeatureTests.cs` guards that both are on in the shipped build.
- The WSL Containers backend uses the same split for its Windows builds, and a single implementation
payload serves both portable targets because a .NET 11 process loads a .NET 10 assembly.

Expand Down
6 changes: 3 additions & 3 deletions docs/wiki/Backends.md
Original file line number Diff line number Diff line change
Expand Up @@ -224,7 +224,7 @@ dotnet add package Purview.Containers.Wsl
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Purview.Containers.Wsl" Version="1.0.0-prerelease.1" />
<PackageReference Include="Purview.Containers.Wsl" Version="1.0.0-prerelease.14" />
</ItemGroup>
</Project>
```
Expand Down Expand Up @@ -253,7 +253,7 @@ dotnet add package Purview.Containers.Docker
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Purview.Containers.Docker" Version="1.0.0-prerelease.1" />
<PackageReference Include="Purview.Containers.Docker" Version="1.0.0-prerelease.14" />
</ItemGroup>
</Project>
```
Expand All @@ -278,7 +278,7 @@ dotnet add package Purview.Containers
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Purview.Containers" Version="1.0.0-prerelease.1" />
<PackageReference Include="Purview.Containers" Version="1.0.0-prerelease.14" />
</ItemGroup>
</Project>
```
Expand Down
13 changes: 4 additions & 9 deletions docs/wiki/Consumer-Requirements.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,5 @@
# Consumer Requirements

> **Experimental.** `Purview.Containers.*` is an experimental project: the public API, the
> defaults and these requirements can change between prereleases, and there is no production
> support guarantee. Treat every version as a preview and pin the exact package version you build
> against.

The WSL Containers backend package is **multi-target**. It ships Windows builds
(`net10.0-windows10.0.19041.0` and `net11.0-windows10.0.19041.0`, the implementations, built on the
`Microsoft.WSL.Containers` projection) and platform-neutral builds (`net10.0` and `net11.0`, facades). A
Expand Down Expand Up @@ -35,7 +30,7 @@ for operation deadlines, resource ownership and native cancellation limits.
| `Purview.Containers.Wsl` | `net10.0`, `net11.0`, `net10.0-windows10.0.19041.0` and `net11.0-windows10.0.19041.0` | The WSL Containers backend: portable facades plus the Windows implementations. **The requirements on this page are its contract.** |
| `Purview.Containers.Docker` | `net10.0` and `net11.0`, any platform | The Docker backend (Testcontainers). Needs a reachable Docker daemon, not a Windows target framework. |
| `Purview.Containers.Environment` | `net10.0` and `net11.0`, any platform | Standalone Docker-compatible CLI bind-sharing resolver; no Aspire, Testcontainers or WSLC dependency. |
| `Purview.Containers.Aspire` | `net10.0` and `net11.0`, any platform | Optional adapter requiring Aspire 13.6.5+ and the Environment package; no backend dependency. |
| `Purview.Containers.Aspire` | `net10.0` and `net11.0`, any platform | Optional adapter requiring Aspire 17.0.0+ and the Environment package; no backend dependency. |

The standalone resolver requires a reachable Linux-container daemon through its selected CLI, working
credential helpers on `PATH`, and client write access to bind-source directories for verification markers.
Expand Down Expand Up @@ -180,8 +175,8 @@ runs on WSLC locally and Docker in CI with no further configuration:
<TargetFramework>net10.0</TargetFramework> <!-- auto: WSLC on Windows, Docker elsewhere -->
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Purview.Containers.PostgreSql" Version="1.0.0-prerelease.1" />
<PackageReference Include="Purview.Containers.Wsl" Version="1.0.0-prerelease.1" />
<PackageReference Include="Purview.Containers.PostgreSql" Version="1.0.0-prerelease.14" />
<PackageReference Include="Purview.Containers.Wsl" Version="1.0.0-prerelease.14" />
</ItemGroup>
</Project>
```
Expand Down Expand Up @@ -269,7 +264,7 @@ unconditionally — every inner build is supported:
<TargetFrameworks>net10.0;net11.0;net10.0-windows10.0.19041.0</TargetFrameworks>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Purview.Containers.Wsl" Version="1.0.0-prerelease.1" />
<PackageReference Include="Purview.Containers.Wsl" Version="1.0.0-prerelease.14" />
</ItemGroup>
```

Expand Down
Loading
Loading