From 66b782e261f1cd928ad6a8482788a65fb484db45 Mon Sep 17 00:00:00 2001 From: James O'Doherty Date: Thu, 4 Jun 2026 22:38:44 -0400 Subject: refactor: simplify architecture and improve documentation - Extract orchestration logic from `internal/cli` into a new `internal/manager` package for better composability. - Migrate technical implementation details from README.md to package-level godoc strings. - Rewrite README.md to be more user-centric, focusing on quick start and usage. - Add comprehensive documentation for exported structs and fields across the project. - Verify all changes with `go fmt`, `go vet`, `golangci-lint`, and full E2E test suite. --- internal/namespace/namespace.go | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) (limited to 'internal/namespace') diff --git a/internal/namespace/namespace.go b/internal/namespace/namespace.go index 54414a9..b05dea2 100644 --- a/internal/namespace/namespace.go +++ b/internal/namespace/namespace.go @@ -1,3 +1,24 @@ +// Package namespace provides primitives for managing Linux user and network +// namespaces, including bootstrapping and pinning. +// +// Rootless Bootstrap Loop & Host-Socket Preservation: +// To achieve rootless network isolation without interfering with the Go runtime's multi-threaded +// scheduler, and to maintain encrypted UDP socket connectivity over the host's network, +// wg-wrap employs an advanced bootstrap loop: +// +// 1. Host-Bound Socket Creation: During the initial host-level start, a UDP socket is opened +// on 0.0.0.0:0 on the host, and its FD is stored in the environment (WG_WRAP_HOST_SOCKET_FD). +// 2. Helper Deployment: An embedded single-threaded C launcher is used to bridge the transition. +// 3. Namespace Transition: The process replaces itself with the C launcher via syscall.Exec. +// 4. Isolation: The launcher performs the unshare(CLONE_NEWUSER | CLONE_NEWNS | CLONE_NEWNET) +// sequence to isolate Mount, User, and Network environments. +// 5. Re-entry: The launcher then execvp's the original wg-wrap binary. +// 6. FDBind Tunnel Initialization: The second instance of wg-wrap wraps the host socket FD +// inside a custom FDBind struct to initialize wireguard-go. +// +// User Namespace Sequence: +// To create a network namespace without root, wg-wrap follows the sequence: +// CLONE_NEWUSER -> CLONE_NEWNET -> Setuid/Setgid -> Configure Interfaces. package namespace import ( -- cgit v1.2.3