wslcsdk 0.3.0

Idiomatic, safe, and asynchronous Rust SDK for Microsoft WSL Containers (WSLC)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

# wslcsdk


<p align="center">
  <b>English</b> | <a href="README_zh.md">简体中文</a>
</p>

Idiomatic, safe, and asynchronous Rust SDK for Microsoft WSL Containers (WSLC).

Built against Microsoft's official **`Microsoft.WSL.Containers` (Version 3.0.1 GA)**, this crate provides modern, memory-safe, and production-grade Rust interfaces to manage WSL-native micro-VM containers.

---

## Features


- **Strict RAII Lifetime Management**: Automatically closes native C handles (`WslcSession`, `WslcContainer`, `WslcProcess`, `WslcCrashDumpSubscription`) upon drop.
- **Streaming Process I/O**: Captures stdout/stderr via native C trampolines and feeds them into bounded asynchronous channels. The receivers it exposes are runtime-agnostic, so no third-party async runtime type leaks into the public API.
- **Two-Layer Typed Error Domain**: `WslcDomainError` mirrors the 19 named HRESULTs of the official header one-to-one, while infrastructure failures stay in the outer `WslcError`. Unrecognized standard HRESULTs are reported by name instead of a misleading generic message.
- **Non-blocking Async Extensions**: Provides `_async` methods offloaded to `tokio::task::spawn_blocking` with COM MTA automatic initialization.
- **Volume and Image Management**: Built-in VHD volume options and image pull/list/delete abstractions.

---

## Installation


Add this crate to your `Cargo.toml`:

```toml
[dependencies]
wslcsdk = "0.3.0"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
```

> **Compatibility**: `wslcsdk 0.2.x` is built on top of `wslcsdk-sys 3.0.1` and requires Windows 11 with WSL 2.9.3+ or 3.0.1+.

---

## Usage Example


```rust,no_run
use wslcsdk::{WslcClient, WslcSignal};

#[tokio::main]

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Initialize unified client (auto environment check, default session, COM MTA lifecycle)
    let client = WslcClient::builder().session_name("my-session").build()?;

    // 2. The builder is already bound to the client's session, so build() takes no argument
    let container = client
        .create_container("docker.io/library/alpine:latest")
        .name("alpine-demo")
        .auto_remove(true)
        .build()?;

    // 3. Start container
    container.start(false)?;

    // 4. Stop and delete
    container.stop(WslcSignal::Sigterm, 10)?;
    container.delete(false)?;

    Ok(())
}
```

---

## License


This project is licensed under the [MIT License](../../LICENSE).