docs(spikes): spike wireguard-go vs boringtun for Unit 4 WireGuard mesh - #488
Conversation
Resolves load-bearing assumption wireguard-implementation (#486). Finds boringtun (pure Rust) the better fit for minimald v1 over wireguard-go (cgo) due to clean Cargo feature-flag gating (R4.7), zero extra build-chain dependencies, and sufficient production maturity for the AllowedIPs subnet-router model required. Closes #486
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughA new spike document is added at ChangesWireGuard Implementation Spike
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/spikes/2026-06-20-wireguard-implementation.md`:
- Around line 85-88: Update the boringtun version reference from 0.6.x
(mid-2025) to 0.7.1 (as of June 2026). Additionally, revise the characterization
of boringtun's development pace in the context section: while it previously
showed an 18-month gap between versions, recent activity demonstrates active
maintenance with version 0.7.0 released in January 2026 containing critical
security updates and 0.7.1 in May 2026. Update the text to reflect this improved
maintenance status and recent security activity rather than only describing
"slower churn."
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 8ab199cf-9d95-4ccf-8a82-0a30724a8b28
📒 Files selected for processing (1)
docs/spikes/2026-06-20-wireguard-implementation.md
|
Revise claim for head 37b11af. |
|
Auto-revise 1 of 3. |
… 2026 Update boringtun version reference from 0.6.x (mid-2025) to 0.7.1 (May 2026), and revise the maintenance characterization to reflect the recovery in early 2026: 0.7.0 released January 2026 with critical security updates, followed by 0.7.1 in May 2026. The ~18-month gap between 0.6.0 and 0.7.0 is now historical context rather than the current state. Updated in four locations: the findings source description, the comparison table maintenance-risk row, the action-item risk-register entry, and the artifacts section version reference. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
Commit pushed:
|
| 2. **Context section amendment:** Update the context paragraph in | ||
| `03-spec-networking.md` ("wireguard-go (Tailscale userspace netstack)") | ||
| and the building-block diagram in `networking-with-diagrams.md` ("wireguard-go | ||
| / Tailscale userspace netstack") to read "boringtun (pure-Rust WireGuard)." |
There was a problem hiding this comment.
MEDIUM — Correctness: action item 2 scope is incomplete
Action item 2 targets the context paragraph (wireguard-go (Tailscale userspace netstack)) and building-block B6 in networking-with-diagrams.md, but following those two edits alone will leave the spec internally inconsistent. The following references also encode wireguard-go for the CLI and are not covered:
- R4.3 (
03-spec-networking.mdline 318):"with wireguard-go bundled so no system WireGuard package is required"— this governs theminimalCLI, notminimald. If boringtun is the chosen implementation for both the daemon and the CLI (reasonable since both are Rust), R4.3 also needs updating. If wireguard-go is intentionally kept for the CLI, action item 2 should be scoped explicitly to daemon-only references to avoid creating an ambiguity. networking-with-diagrams.mdDiagram 4,LapWGnode (approximately line 287):wireguard-go peer (bundled in minimal CLI or system WG client)— a CLI-specific diagram node inside B6's conceptual scope but separate from the B6 label text.networking-with-diagrams.mdOption A prose (approximately lines 585–588):"Each minimald is a wireguard-go peer"and"The laptop becomes a peer via minimal CLI — wireguard-go is bundled"— two explicit wireguard-go CLI references that would remain after action item 2 is applied.
If boringtun covers both minimald and minimal CLI, all four locations need amendment. If the spike is intentionally scoped to the daemon only, action items 1 and 2 should say so explicitly and item 2 should be narrowed to the daemon-side B6 label rather than the whole building-block section. As written, R4.3 and the CLI diagram text will contradict R4.1 and the updated context paragraph after the action items are applied.
Action item 2 previously named only the context paragraph and B6 label, leaving R4.3 (CLI requirement), the UC2 WG diagram node, the deployment- model LapWG node, and the Option A prose inconsistent after the action items are applied. boringtun applies to both minimald and the minimal CLI (both pure Rust), so all six wireguard-go references in the networking spec must be updated together. Action item 2 now enumerates them explicitly.
|
Commit pushed:
|
| - **Source:** `boringtun` crate on crates.io (Cloudflare), version 0.7.1 (May | ||
| 2026; preceded by 0.7.0 in January 2026 with critical security updates, and | ||
| 0.6.0 in July 2023). GitHub: `github.com/cloudflare/boringtun`. Development | ||
| pace had an ~18-month gap between 0.6.0 and 0.7.0, but resumed actively in |
There was a problem hiding this comment.
MEDIUM · Correctness
The stated gap of "~18 months" is arithmetically inconsistent with the dates given. July 2023 → January 2026 is approximately 30 months (~2.5 years), not 18:
- July 2023 + 12 months = July 2024
- July 2024 + 6 months = January 2025
- January 2025 + 12 months = January 2026
- Total: 30 months
The same figure propagates into action item 4 (line 238–239), which sets the risk-register re-evaluation checkpoint at "18 months of the prior release." That threshold is calibrated against the incorrect gap, so it would fire for any 19-month silence even though the historical maintenance gap was 30 months. The checkpoint should read "30 months" (or "2.5 years") to match the actual evidence.
| - **Integration into non-Go binaries:** wireguard-go is a Go program. Embedding | ||
| it in a Rust binary requires one of two paths: | ||
| - **Subprocess:** Run the `wireguard-go` binary as a child process; communicate | ||
| via its JSON configuration socket. minimald manages the lifecycle alongside |
There was a problem hiding this comment.
LOW · Correctness
wireguard-go’s inter-process interface is the WireGuard UAPI protocol — a line-based, newline-delimited key=value text protocol over a Unix socket — not a JSON protocol. A typical exchange looks like:
listen_port=51820
public_key=<hex>
allowed_ip=10.0.0.0/8
Describing it as a "JSON configuration socket" is inaccurate. This matters for the subprocess escalation path documented here (the only wireguard-go path retained for potential future use). The corrected phrasing would be "communicate via its UAPI socket" or "communicate via its WireGuard UAPI text socket."
|
Pull request created: #490
|
Closes #486
Resolves load-bearing assumption
wireguard-implementationfrom spec-networking Unit 4 (R4.1).Summary
partial— wireguard-go's production maturity claim (Tailscale scale) is confirmed, but the practical recommendation for minimald v1 is boringtun.docs/spikes/2026-06-20-wireguard-implementation.mdKey findings
Production maturity (subnet-router model): wireguard-go is more extensively battle-tested for subnet-router via Tailscale's production stack. boringtun is production-proven in Cloudflare WARP and Mullvad VPN — sufficient for minimald v1's AllowedIPs-based subnet routing.
CI build-chain: The "reduced marginal CI cost" hypothesis holds for gvproxy-style pure-Go builds, but wireguard-go's cgo path (
buildmode=c-shared) additionally requires a C cross-compiler per target architecture — absent from gvproxy's pure-Go build — and a custom Go shim (wireguard-go has no C-exported API upstream).Recommendation: boringtun — clean Cargo feature flag for R4.7 (no binary-size impact when unconfigured), zero extra build-chain dependencies, and equivalent WireGuard protocol support for the v1 subnet-router pattern. The cgo integration path is substantially more complex than the hypothesis assumed.
Action items for Unit 4 planning
03-spec-networking.md: replace wireguard-go/cgo with boringtunnetworking-with-diagrams.mdbuilding-block B6: update to boringtunboringtunin[workspace.dependencies]behind thewgCargo feature when Unit 4 implementation beginsMerging this PR closes the spike sub-issue and advances the spec-networking Unit 4 planning to implementation.
Summary by CodeRabbit