docs: ctor test pattern, VM guide, reorder NAT64, rework holepunching

Frando · claude · Frando · commit 57c1925d0874 · 2026-03-02T21:58:39.000+01:00
- Add ctor paragraph for test namespace init in getting-started
- Reorder IPv6 NAT table to put NAT64 first after None
- Dial down motivation criticism, add performance testing use case
- Add Running in a VM guide page covering patchbay-vm
- Rework holepunching reference with better prose, mark as advanced
- Update SUMMARY with VM page

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -9,10 +9,11 @@
 - [Building Topologies](guide/topology.md)
 - [NAT and Firewalls](guide/nat-and-firewalls.md)
 - [Running Code in Namespaces](guide/running-code.md)
+- [Running in a VM](guide/vm.md)
 
 # Reference
 
 - [IPv6 Deployments](reference/ipv6.md)
 - [Network Patterns](reference/patterns.md)
-- [NAT Hole-Punching](reference/holepunching.md)
+- [NAT Hole-Punching (Advanced)](reference/holepunching.md)
 - [TOML Simulation Reference](reference/toml-reference.md)
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
@@ -70,6 +70,28 @@ async fn async_main() -> anyhow::Result<()> {
 If you skip this call, `Lab::new()` will fail because the process lacks
 the network namespace capabilities it needs.
 
+In integration tests, you can avoid the `main` / `async_main` split by
+using a `#[ctor]` initializer that runs before any test thread is spawned:
+
+```rust
+#[cfg(test)]
+#[ctor::ctor]
+fn init() {
+    patchbay::init_userns().expect("failed to enter user namespace");
+}
+
+#[tokio::test]
+async fn my_test() -> anyhow::Result<()> {
+    let lab = patchbay::Lab::new().await?;
+    // ...
+    Ok(())
+}
+```
+
+The `ctor` crate runs the function at load time, before `main` or the
+test harness starts. This keeps your test functions clean and avoids
+repeating the namespace setup in every binary.
+
 ## Creating a lab
 
 A `Lab` is the top-level container for a topology. When you create one, it
diff --git a/docs/guide/motivation.md b/docs/guide/motivation.md
@@ -10,11 +10,12 @@ WiFi-to-cellular handoff without dropping state. Those questions require
 actual network stacks with actual packet processing, and the only way most
 teams answer them today is by deploying to staging and hoping for the best.
 
-Some projects work around this with Docker Compose topologies, Mininet
-graphs, or bespoke iptables scripts. These approaches share a few
-drawbacks: they require root, they leave state behind when something
-crashes, they are difficult to parameterize from a test harness, and they
-tend to drift from the real-world conditions they are meant to represent.
+Tools like Docker Compose, Mininet, and custom iptables scripts can help,
+but each comes with trade-offs around privilege requirements, cleanup
+reliability, and how easily you can parameterize topologies from a test
+harness. patchbay was built to make this kind of testing ergonomic for Rust
+projects: no root, no cleanup, and a builder API that fits naturally into
+`#[tokio::test]` functions.
 
 ## What patchbay does
 
@@ -34,34 +35,41 @@ automatically.
 
 ## Where it fits
 
-patchbay is a testing and development tool. It is designed for two primary
+patchbay is a testing and development tool, designed for three primary
 use cases:
 
 **Integration tests.** Write `#[tokio::test]` functions that build a
 topology, run your networking code inside it, and assert on outcomes. Each
 test gets an isolated lab with its own address space, so tests can run in
 parallel without interfering with each other or with the host.
 
+**Performance and regression testing.** Apply link conditions to simulate
+constrained networks (3G, satellite, lossy WiFi) and measure throughput,
+latency, or reconnection time under controlled impairment. Because tc
+netem operates at the kernel level, the shaping is realistic enough for
+comparative benchmarks, though absolute numbers will differ from hardware
+links due to scheduling overhead and the absence of real radio or cable
+physics.
+
 **Interactive experimentation.** Build a topology in a binary or script,
 attach to device namespaces with shell commands, and observe how traffic
 flows. This is useful for understanding NAT behavior, debugging
 connectivity issues, or validating protocol assumptions before writing
 tests.
 
-patchbay is not a production networking tool, a container orchestrator, or
-a replacement for network simulation frameworks like ns-3. It operates at
-the kernel namespace level with real TCP/IP stacks, not at the packet
-simulation level. This means the fidelity is high (you are testing against
-real Linux networking), but the scale is limited to what a single machine
-can support (typically dozens of namespaces, not thousands).
+patchbay operates at the kernel namespace level with real TCP/IP stacks,
+not at the packet simulation level. This means the fidelity is high (you
+are testing against real Linux networking), but the scale is limited to
+what a single machine can support (typically dozens of namespaces, not
+thousands).
 
 ## Scope of this book
 
 The **Guide** section walks through patchbay's concepts in order: setting
-up a lab, building topologies, configuring NAT and firewalls, and running
-code inside namespaces. Each chapter builds on the previous one and
-includes runnable examples.
+up a lab, building topologies, configuring NAT and firewalls, running code
+inside namespaces, and running labs in a VM on non-Linux hosts. Each
+chapter builds on the previous one and includes runnable examples.
 
 The **Reference** section covers specialized topics in depth: real-world
-IPv6 deployment patterns, NAT traversal and hole-punching mechanics,
-network event simulation recipes, and the TOML simulation file format.
+IPv6 deployment patterns, network event simulation recipes, NAT traversal
+and hole-punching internals, and the TOML simulation file format.
diff --git a/docs/guide/nat-and-firewalls.md b/docs/guide/nat-and-firewalls.md
@@ -97,9 +97,9 @@ let router = lab.add_router("r")
 | Mode | Description |
 |------|-------------|
 | `None` | No IPv6 NAT. Devices get globally routable addresses. This is the default and the most common real-world configuration. |
+| `Nat64` | Stateless IP/ICMP Translation (RFC 6145). Allows IPv6-only devices to reach IPv4 hosts through the well-known prefix `64:ff9b::/96`. The most important v6 NAT mode in practice; used by major mobile carriers. |
 | `Nptv6` | Network Prefix Translation (RFC 6296). Performs stateless 1:1 prefix mapping at the border, preserving end-to-end connectivity while hiding internal prefixes. |
 | `Masquerade` | IPv6 masquerade, analogous to IPv4 NAPT. Rare in production but useful for testing applications that must handle v6 address rewriting. |
-| `Nat64` | Stateless IP/ICMP Translation (RFC 6145). Allows IPv6-only devices to reach IPv4 hosts through the well-known prefix `64:ff9b::/96`. |
 
 ### NAT64
 
diff --git a/docs/guide/vm.md b/docs/guide/vm.md
@@ -0,0 +1,119 @@
+# Running in a VM
+
+patchbay requires Linux network namespaces, which means it cannot run
+natively on macOS or Windows. The `patchbay-vm` crate solves this by
+wrapping your simulations and tests in a QEMU Linux VM, giving you the
+same experience on any development machine.
+
+## Installing patchbay-vm
+
+```bash
+cargo install --git https://github.com/n0-computer/patchbay patchbay-vm
+```
+
+## Running simulations
+
+The `run` command boots a VM (or reuses a running one), stages the
+simulation files and binaries, and executes them inside the guest:
+
+```bash
+patchbay-vm run ./sims/iperf-baseline.toml
+```
+
+Results and logs are written to the work directory (`.patchbay-work/` by
+default). You can pass multiple simulation files, and they run
+sequentially in the same VM.
+
+### Controlling the patchbay version
+
+By default, `patchbay-vm` downloads the latest release of the patchbay
+runner binary. You can pin a version, build from a Git ref, or point to a
+local binary:
+
+```bash
+patchbay-vm run sim.toml --patchbay-version v0.10.0
+patchbay-vm run sim.toml --patchbay-version git:main
+patchbay-vm run sim.toml --patchbay-version path:/usr/local/bin/patchbay
+```
+
+### Binary overrides
+
+If your simulation references custom binaries (test servers, protocol
+implementations), you can stage them into the VM:
+
+```bash
+patchbay-vm run sim.toml --binary myserver:path:./target/release/myserver
+```
+
+The binary is copied into the guest's work directory and made available
+at the path the simulation expects.
+
+## Running tests
+
+The `test` command cross-compiles your Rust tests for musl, stages the
+test binaries in the VM, and runs them:
+
+```bash
+patchbay-vm test
+patchbay-vm test --package patchbay
+patchbay-vm test -- --test-threads=4
+```
+
+This is the recommended way to run patchbay integration tests on macOS.
+The VM has all required tools pre-installed (nftables, iproute2, iperf3)
+and unprivileged user namespaces enabled.
+
+## VM lifecycle
+
+The VM boots on first use and stays running between commands. Subsequent
+`run` or `test` calls reuse the existing VM, which avoids the 30-60
+second boot time on repeated invocations.
+
+```bash
+patchbay-vm up        # Boot the VM (or verify it is running)
+patchbay-vm status    # Show VM state, SSH port, mount paths
+patchbay-vm down      # Shut down the VM
+patchbay-vm cleanup   # Remove stale sockets and PID files
+```
+
+You can also SSH into the guest directly for debugging:
+
+```bash
+patchbay-vm ssh -- ip netns list
+patchbay-vm ssh -- nft list ruleset
+```
+
+## How it works
+
+`patchbay-vm` downloads a Debian cloud image (cached in
+`~/.local/share/patchbay/qemu-images/`), creates a COW disk backed by
+it, and boots QEMU with cloud-init for initial provisioning. The guest
+gets SSH access via a host-forwarded port (default 2222) and three shared
+mount points:
+
+| Guest path | Host path | Access | Purpose |
+|------------|-----------|--------|---------|
+| `/app` | Workspace root | Read-only | Source code and simulation files |
+| `/target` | Cargo target dir | Read-only | Build artifacts |
+| `/work` | Work directory | Read-write | Simulation output and logs |
+
+File sharing uses virtiofs when available (faster, requires virtiofsd on
+the host) and falls back to 9p. Hardware acceleration is auto-detected:
+KVM on Linux, HVF on macOS, TCG emulation as a last resort.
+
+## Configuration
+
+All settings have sensible defaults. Override them through environment
+variables when needed:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `QEMU_VM_MEM_MB` | 4096 | Guest RAM in megabytes |
+| `QEMU_VM_CPUS` | 4 | Guest CPU count |
+| `QEMU_VM_SSH_PORT` | 2222 | Host port forwarded to guest SSH |
+| `QEMU_VM_NAME` | patchbay-vm | VM instance name |
+| `QEMU_VM_DISK_GB` | 40 | Disk size in gigabytes |
+
+VM state lives in `.qemu-vm/<name>/` in your project directory. The disk
+image uses COW backing, so it only consumes space for blocks that differ
+from the base image.
diff --git a/docs/reference/holepunching.md b/docs/reference/holepunching.md
