sys-lib 0.3.0

System facts for Rust services: OS, CPU, memory, disks, network, host, this process, virtualization, power, and device identity, container-aware by default, plus build info, instance info, and a process guard. No subprocesses, zero third-party dependencies.
Documentation
# sys-lib v0.3.0 - Boot Kit

**The first working release: everything a service needs in its first milliseconds.** v0.3.0 ships OS identity and the Linux distribution, CPU counts and names with a container-aware `cpu::available()`, the host name, the user, build info, instance info, and the process guard: the boot kit WASP's phase 0 is written against.

## What is sys-lib?

<strong>sys-lib</strong> answers the questions a program asks about the machine it runs on, with one plain function call each, on Linux, macOS, and Windows: the operating system and distribution, the CPU, memory, disks, network interfaces and traffic, the host, this process, virtualization and containers, power, and an application-scoped device id. It also carries the boot kit a long-running service needs in its first milliseconds: build info, instance info, and a process guard. It is container-aware, reports unknown facts as unknown, never runs another program, never starts a thread, and has no third-party runtime dependencies.

## What's in 0.3.0

```toml
[dependencies]
sys = { package = "sys-lib", version = "0.3" }
```

- **`os`**: `name()` ("Ubuntu 24.04.1 LTS", "macOS 15.1 Sequoia", "Windows 11 Pro"), `version()`, `kernel()`, `distro()` and `distro_id()` on every OS, `is_like("debian")`, every os-release field through `os_release()`, the `const` `kind()` and `is_*()` checks, and `info()`. On Linux the distribution comes from os-release, then the legacy release files (`lsb-release`, the Red Hat family's sentences, `SuSE-release`, `alpine-release`, `debian_version`, and others), then "Linux".
- **`cpu`**: `logical()`, `physical()`, `available()`, `name()` (cleaned: "AMD Ryzen 9 9950X3D"), `raw_name()`, `vendor()`, `arch()`, `is_64bit()`, `is_32bit()`. `available()` is what this process may really use: the affinity mask, intersected with the cgroup cpuset, then limited by the cgroup v1 or v2 CPU quota (rounded up), and the Windows job object's CPU rate cap.
- **`host::name()`**, **`process::id()`**, **`process::user()`**, **`process::is_elevated()`**.
- **The process guard**, `process::guard("site")?`: a single-instance lock the OS releases even after `kill -9`, a pid file, `umask(0o027)`, and the open-file limit raised to 65 536, refusing to start (with nothing changed) when the hard limit is below 1 024. The lock directory is created owner-only and refused when it is a symlink, writable by others, owned by another user, or on a network filesystem; the lock file is opened without following links and checked to be the file inspected. `Guard::builder` sets every option; `GuardReport` says what was done.
- **Build info**: `sys::build::emit()` in the application's `build.rs` and `sys::build_info!()` at run time give the commit, the dirty flag, the build time (`SOURCE_DATE_EPOCH` honoured), profile, target, `rustc`, and features, with `public()` for health endpoints (name and version only). `build::emitter()` turns parts off.
- **Instance info**: `Instance::start()` gives a ULID instance id, the start time, the host, the pid, and the user, written as one log line or JSON.
- **`Error`**, **`Bytes`**, **`Percent`**: every error says what failed and what to do; `Bytes` prints IEC by default ("41.2 GiB"), SI with `{:#}`, or JEDEC.

## How it was tested

- **A distribution corpus of 64 real systems**, captured from container images by CI: Debian 9 to 13, Ubuntu 12.04 to 25.04, Fedora, CentOS 5 to Stream 10, Rocky, Alma, Oracle, RHEL UBI, Amazon Linux 1, 2, and 2023, Azure Linux, openEuler, openSUSE, SLE, Alpine, Arch, Manjaro, Gentoo, Void, Slackware, Kali, Parrot, Mint, Wolfi, distroless, and more. Each answer is checked against what a shell reads from the same os-release, and the legacy files against os-release. The corpus found two bugs before release: openEuler's `ID=openEuler` was rejected for its capitals, and Manjaro's and Photon's `lsb-release` names gave ids no os-release uses.
- **Fixture machines**, including a new `docker-cgroup1-limited` captured on a real cgroup v1 host (Ubuntu 20.04 in a virtual machine on a CI runner).
- **Live comparison** on every CI runner against the OS's own tools: `uname`, `id`, `getconf`, `nproc`, and a shell on Linux; `sysctl` and `sw_vers` on macOS; CIM and .NET on Windows.
- **The guard across processes**: a second copy is refused with the first copy's pid, and a holder killed without warning leaves the lock free.
- **Attack tests** for path and value injection through the environment (T4), lock-file attacks (T9), the umask race (T10), disclosure through build info (T11), and subprocess hijacking with fake programs on `PATH` (T16). The T4 test also checks that the Linux backend opens only a reviewed list of files.
- **Fuzz targets for all 12 parsers** (20 seconds each on every push, 10 minutes each nightly) and **Miri** over the parsers, units, and formatting on every push.
- 64 threads reading every fact at first use see one value.

## What changed

- `build::emitter()` arrives now instead of in 0.4 (D-032). `cpu::Vendor` gains Broadcom, Marvell, Fujitsu, HiSilicon, and Microsoft (D-033).
- The build helper ignores a `HEAD` that names anything but a well-formed ref, so a tampered repository cannot add a line to the build script's output (D-037).
- `GuardWarning::ThreadsAlreadyRunning` is reported on Unix only: Windows has no umask, and every Windows process starts with loader threads (D-035).
- `docs/API.md` was audited against the code item by item and corrected where the code is the better design (D-034).

## What's next

`0.4.0`, live readings: memory and swap with container limits, CPU usage and load, disks and disk I/O rates, network interfaces, traffic and connections, pressure and out-of-memory events, and this process's memory, CPU time, threads, and limits.