go-winio

go-winio is Microsoft’s library of low-level Windows IO primitives for Go programs, built directly on raw Win32 and NT syscalls rather than any cross-platform abstraction. Its core contribution is turning Windows named pipes into a standard net.Conn-compatible transport by driving overlapped IO through a shared IO completion port, so pipe reads and writes integrate with Go’s goroutine scheduler instead of blocking OS threads.

Beyond named pipes, the repository bundles a set of narrowly-scoped Windows subsystem wrappers: NTFS backup-stream and extended-attribute handling, security descriptor manipulation, process privilege adjustment, reparse point parsing, Hyper-V sockets, VHD and WIM image utilities, and an ETW (Event Tracing for Windows) provider implementation with a logrus hook. Each concern lives in its own file or subpackage, letting consumers import only what they need.

This is foundational infrastructure for the Windows container and virtualization ecosystem — it underpins projects like containerd, Moby/Docker, and the Windows Host Compute Service stack, which explains its emphasis on correctness for low-level OS interop over surface-level ergonomics. The //sys syscall directives and generated zsyscall_windows.go bindings reflect a deliberate choice to stay close to the Win32 API surface rather than layer on abstractions.

What You Get

• Named pipe client/server support exposed as a standard net.Conn/net.Listener, usable anywhere Go code expects a stream connection
• Non-blocking overlapped IO for arbitrary Win32 file handles, driven by a shared IO completion port instead of blocking OS threads
• NTFS backup API bindings (BackupRead/BackupWrite) and a backuptar package for streaming Windows file metadata (ACLs, alternate data streams, reparse points) into and out of tar archives
• Security descriptor and process privilege helpers (pkg/security, privilege.go) for reading/adjusting Windows ACLs and token privileges
• An ETW (Event Tracing for Windows) provider implementation (pkg/etw) with a ready-made logrus hook (pkg/etwlogrus) for structured event tracing
• VHD and WIM disk/image format utilities (vhd, wim) for creating and inspecting Windows virtual disk and imaging files
• Hyper-V socket (hvsock) support for host-to-guest communication in virtualization scenarios

Common Use Cases

• Implementing a Windows container runtime or shim (containerd/Moby-style) that needs named-pipe IPC with the Host Compute Service
• Building a Windows service or agent that must copy files while preserving NTFS ACLs, alternate data streams, and reparse points
• Adding ETW-based structured tracing to a Go service running on Windows, alongside existing logrus logging
• Managing Hyper-V guest communication channels or working with VHD/WIM image files as part of a virtualization or provisioning tool
• Adjusting Windows process token privileges (e.g. SeBackupPrivilege) for tools that need elevated backup/restore access

Under The Hood

Architecture The package is organized as a flat set of concern-per-file modules at the root (pipe.go, file.go, backup.go, ea.go, sd.go, hvsock.go, privilege.go, reparse.go) alongside self-contained subpackages under internal/ (computestorage, fs, interop, socket, stringbuffer) and pkg/ (etw, etwlogrus, guid, security, process, bindfilter, fs), plus standalone format packages for vhd/, wim/, and backuptar/. Everything is gated behind //go:build windows build tags, and the whole library is built directly on syscalls rather than cross-platform abstractions. The central architectural pattern is the shared IO completion port initialized once (initIO/ioCompletionPort) and serviced by a background goroutine (ioCompletionProcessor), which every overlapped-IO-based type (named pipes, generic Win32 file handles) registers against — this is what lets blocking Win32 async APIs present as ordinary non-blocking Go io.Reader/io.Writer/net.Conn implementations without spinning up a thread per handle.

Tech Stack The module targets Go 1.23 and has a deliberately thin dependency footprint: golang.org/x/sys for raw Windows syscalls, golang.org/x/tools supporting code generation, and github.com/sirupsen/logrus consumed only by the optional pkg/etwlogrus hook. Low-level Win32/NT function bindings are not hand-written — they’re declared via //sys comment directives and generated into zsyscall_windows.go by the bundled tools/mkwinsyscall code generator, invoked through go:generate. Continuous integration runs via GitHub Actions (ci.yml), with golangci-lint enforcing style and a DCO bot enforcing signed-off commits on every pull request.

Code Quality The repository carries roughly twenty _test.go files spanning nearly every subsystem — pipes, extended attributes, security descriptors, Hyper-V sockets, GUIDs, ETW providers, VHDs, and tar streaming — built on Go’s standard testing package. Error handling favors explicit, typed Windows error values (e.g. ErrFileClosed, ErrTimeout implementing net.Error) over generic errors, and the generated syscall layer keeps unsafe pointer arithmetic isolated from the public API surface. Being Windows-only, most of this code cannot be exercised in a typical Linux CI runner without a Windows build agent, so test coverage depth is harder to verify from the repository alone than for cross-platform libraries.

What Makes It Unique go-winio’s distinguishing choice is going straight to the NT/Win32 syscall layer instead of wrapping a higher-level Windows API, which is what lets it implement things the Go standard library structurally cannot: named pipes as first-class net.Conn, NTFS backup-stream semantics that preserve ACLs and alternate data streams, and ETW tracing. Its adoption as core plumbing inside containerd and Moby’s Windows container support is a strong signal that the abstractions it chose (completion-port-backed overlapped IO, backup-stream tar mapping) hold up under production use in container runtimes rather than just toy examples.