zlayer-hns

Safe Rust wrapper for the Windows Host Compute Network Service (HCN v2).

Overview

HCN is the networking half of the Windows container stack — companion to the Host Compute Service (HCS) wrapped in zlayer-hcs. The underlying surface lives in computenetwork.dll. This crate is the authoritative HCN FFI boundary for ZLayer: it wraps the raw entry points behind RAII handle types, JSON schema types matching hcsshim/hcn v2, and high-level helpers for the common case of attaching a container to an overlay network through an HCN namespace.

It backs Windows container networking in zlayer-overlay and zlayer-agent — endpoint creation, network attach, and the HNS endpoint DNS plumbing that makes service discovery work for Windows containers.

Platform

Windows only. The crate root is gated with #![cfg(windows)], so on every other platform it compiles to an empty stub and callers can depend on it unconditionally.

The crate carries #![allow(unsafe_code)] because it is the single allowed location in the workspace for computenetwork.dll FFI plus GetAdaptersAddresses traversal. Every unsafe site has a SAFETY: comment.

Public API

One module per HCN concern:

zlayer_hns::network::Network — RAII handle for an HCN network: create, open, delete, modify, query, create_transparent (the helper that creates the L2-bridged network ZLayer's overlay attaches to), id, handle. Module-level list(query_json) returns all network GUIDs.
zlayer_hns::endpoint::Endpoint — RAII handle for an HCN endpoint: create, open, delete, modify, query_properties, query_stats, primary_ip, id, handle. Module-level list(query_json) returns all endpoint GUIDs.
zlayer_hns::namespace::Namespace — RAII handle for an HCN namespace (the HCS-side "netns" abstraction): create_host_default, create, open, delete, add_endpoint, remove_endpoint, modify_json, query, list_endpoints, id, handle. Module-level list returns namespace GUIDs.
zlayer_hns::attach::EndpointAttachment — High-level helper that bundles endpoint + namespace creation for the overlay-attach path. create_overlay(...) wires up an endpoint on the chosen network with a fresh namespace; teardown(self) reverses both. endpoint_id, namespace_id, and ip accessors expose the ids needed by HcsRuntime. Module-level helpers list_owned_endpoints(owner_tag) and delete_endpoint_and_namespace(endpoint_id, namespace_id) cover crash- recovery cleanup.
zlayer_hns::adapter::find_primary_adapter plus the ZLAYER_UPLINK_ENV constant ("ZLAYER_HCN_UPLINK_ADAPTER") — Picks (or honors an override for) the host NIC the transparent network bridges through.
zlayer_hns::error::{HnsError, HnsResult} — thiserror-based error type classifying HCN HRESULT codes.
zlayer_hns::handle — Raw HCN handle wrappers with Drop impls (OwnedNetwork, OwnedEndpoint, OwnedNamespace).
zlayer_hns::schema — serde-driven schema v2 types (HostComputeNetwork, HostComputeEndpoint, HostComputeNamespace, EndpointStats, ...).

Use from ZLayer

Consumed primarily by:

zlayer-agent — HcsRuntime invokes EndpointAttachment::create_overlay at container-create time so each Windows container lands on the ZLayer overlay with the right IP, DNS, and policy. The same path handles HNS endpoint DNS plumbing so service-discovery names resolve inside Windows containers.
zlayer-overlay — Coordinates IP allocation against the HCN network's subnet so the agent's allocator and the HNS-side state agree.

This is an internal ZLayer crate. The workspace version = "0.0.0-dev" is unpublished; consume it via the workspace path dependency, not crates.io.

When to edit this crate

Edit zlayer-hns when you need to:

Wrap a new computenetwork.dll entry point (always behind a safe API + a SAFETY: comment).
Extend the v2 schema to expose a new HCN field.
Change how transparent networks are constructed (Network::create_transparent).
Adjust the overlay-attach contract — endpoint/namespace creation order, DNS records on the endpoint, IP plumbing — used by HcsRuntime.
Fix uplink-adapter selection in adapter::find_primary_adapter.

Overlay routing, IP allocation, and WireGuard tunnels live in zlayer-overlay, not here.