zlayer_hns/lib.rs
1//! Safe Rust wrapper for the Windows Host Compute Network Service (HCN v2).
2//!
3//! HCN is the networking half of the Windows container stack — companion to
4//! the Host Compute Service (HCS). The underlying surface lives in
5//! `computenetwork.dll`. This crate wraps those raw calls with RAII handle
6//! types, async-ready helpers around the synchronous HCN API, JSON schema
7//! types matching `hcsshim/hcn` v2, and high-level `NetAttacher`-friendly
8//! abstractions for attaching containers to networks via HCN namespaces.
9//!
10//! The crate is Windows-only. On every other platform it compiles to an
11//! empty stub so callers can depend on it unconditionally.
12//!
13//! # `unsafe` policy
14//!
15//! This crate is the authoritative Windows HCN FFI boundary for `ZLayer`. It
16//! exists specifically to wrap the unsafe `computenetwork.dll` entry points
17//! behind safe, typed Rust APIs, so `unsafe` is allowed at the crate level
18//! here even though the workspace-wide policy (`-W unsafe-code`) forbids it
19//! everywhere else. Every `unsafe` block, `unsafe impl`, `unsafe fn`, and
20//! `unsafe` method in this crate carries a `SAFETY:` comment explaining why
21//! the required invariants hold — do not add a new `unsafe` site without one.
22
23#![cfg(windows)]
24#![allow(unsafe_code)]
25// FFI-boundary lints: this crate's entire job is marshaling data into raw
26// pointers for the HCN C ABI. We take `&mut x` / `&x` borrows and hand
27// them to `Hcn*` entry points that take `*mut T` / `*const T`; we cast
28// between related pointer shapes (e.g. the stable `*const c_void` alias
29// in `handle.rs` vs the `*mut c_void` out-params HCN returns); and we
30// navigate `GetAdaptersAddresses`'s variable-length IP_ADAPTER_ADDRESSES_LH
31// linked list by casting from `*const u8` after byte-offset arithmetic.
32// Each site is inside an `unsafe` block with a `SAFETY:` comment; the
33// workspace-wide policy for these lints remains in force everywhere else.
34#![allow(
35 clippy::borrow_as_ptr,
36 clippy::ptr_as_ptr,
37 clippy::ptr_cast_constness,
38 clippy::cast_ptr_alignment,
39 clippy::cast_possible_wrap
40)]
41
42pub mod adapter;
43pub mod attach;
44pub mod endpoint;
45pub mod error;
46pub mod handle;
47pub mod namespace;
48pub mod network;
49pub mod schema;