8000 docs(spec-networking): minimald networking -- PTask network modes, DNS, egress/ingress, WireGuard mesh by gominimal-aw-bot[bot] · Pull Request #482 · gominimal/minimal · GitHub
[go: up one dir, main page]
Skip to content

docs(spec-networking): minimald networking -- PTask network modes, DNS, egress/ingress, WireGuard mesh - #482

Merged
norrietaylor merged 2 commits into
mainfrom
spec/minimald-networking-13402276e247a84a
Jun 20, 2026
Merged

docs(spec-networking): minimald networking -- PTask network modes, DNS, egress/ingress, WireGuard mesh#482
norrietaylor merged 2 commits into
mainfrom
spec/minimald-networking-13402276e247a84a

Conversation

@gominimal-aw-bot
@gominimal-aw-bot gominimal-aw-bot Bot commented Jun 19, 2026 •
edited by coderabbitai Bot
Loading
Copy link
Copy Markdown
Contributor

Summary

Adds a structured SDD spec for the minimald networking epic (tracking issue #478).

The spec covers seven use cases (UC1-UC7) across five deployment models:

  • Unit 1 -- gvproxy switch and PTask network modes (UC1, UC6): one gvproxy per host, no-net/host-net/own-IP modes, same-host PTask-to-PTask connectivity.
  • Unit 2 -- Egress, ingress policy, and VM-wide controls (UC3, UC4, UC5): per-PTask egress allowlists, static and dynamic ingress port mappings, VM-wide egress for libkrun-VM deployment models.
  • Unit 3 -- DNS hostname management (UC2a, UC2c): DNS-resolvable names for PTasks and network-accessible minimald instances; local browser access by hostname.
  • Unit 4 -- WireGuard mesh and remote browser access (UC7, UC2b): wireguard-go/boringtun mesh with minimald as subnet router; HTTPS reverse proxy (mTLS/OIDC) for no-client remote browser access.

Building blocks: one gvproxy (gvisor-tap-vsock) per host, libkrun VMs, wireguard-go or boringtun, mTLS/OIDC HTTPS proxy -- all rootless per-invocation.

Five open design questions are documented (DNS mechanism, egress default policy, dynamic port-mapping API, WireGuard key exchange v1 UX, HTTPS proxy cert management).

Next steps for a reviewer

Please review and merge this spec PR to advance the tracking issue #478 from the spec phase into triage. Merging triggers the architecture phase automatically (sdd-triage-arch starts on the sdd:triage label).

Refs #478

Generated by sdd-spec for issue #478 · ◷

Closes #481

Summary by CodeRabbit

  • Documentation
    • Added a detailed networking specification for minimald, covering PTask isolation modes, DNS hostname behavior, per-PTask egress allowlists and ingress port mappings (including own-IP routing), VM-wide egress controls for applicable deployments, and same-host PTask-to-PTask communication. 8000
    • Documented remote connectivity design, including authenticated WireGuard mesh access and HTTPS reverse-proxy requirements, plus an SSH port-forwarding fallback when needed.

@gominimal-aw-bot
docs(spec-networking): add minimald networking spec for #478
e79fdc5 
Specifies the full networking stack for minimald and PTasks across
five deployment models: PTask network modes (UC1/UC6), egress/ingress
policy (UC3/UC4/UC5), DNS hostname management (UC2a/UC2c), and
WireGuard mesh with HTTPS reverse proxy (UC7/UC2b).

Building blocks: one gvproxy per host as a shared switch, libkrun VMs
on macOS, wireguard-go/boringtun for the authenticated remote mesh,
and an mTLS/OIDC HTTPS reverse proxy on minimald.

Four demoable units with R{unit}.{seq} requirements, each with
1-2 proof artifacts that fail on an empty PR.

Refs #478
@gominimal-aw-bot gominimal-aw-bot Bot mentioned this pull request Jun 19, 2026
Closed
@github-actions github-actions Bot mentioned this pull request Jun 19, 2026
Closed
@coderabbitai
coderabbitai Bot commented Jun 19, 2026 •
edited
Loading
Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6b42a9c9-20ed-4a17-ab1c-097712f98ed9

📥 Commits

Reviewing files that changed from the base of the PR and between e79fdc5 and 0a59d39.

📒 Files selected for processing (1)
  • docs/specs/03-spec-networking/03-spec-networking.md
✅ Files skipped from review due to trivial changes (1)
  • docs/specs/03-spec-networking/03-spec-networking.md
📝 Walkthrough

Walkthrough

Adds a new planned specification document (docs/specs/03-spec-networking/03-spec-networking.md) for the minimald networking stack. The document covers architecture assumptions, five deployment models, seven use cases, four demoable units (switch/mode semantics, egress/ingress policy, DNS lifecycle, WireGuard/HTTPS remote connectivity), non-goals, design decisions, security considerations, and verification commands.

Changes

minimald Networking Specification

Layer / File(s) Summary
Architecture overview, deployment models, and use cases
docs/specs/03-spec-networking/03-spec-networking.md		 Defines gvproxy-per-host architecture assumptions, DM1–DM5 deployment models, goals, and seven user-facing use cases (PTask isolation modes, DNS, egress/ingress policy, VM-wide egress, local P2P, WireGuard mesh).
Unit 1 (switch/mode semantics) and Unit 2 (egress/ingress policy)
docs/specs/03-spec-networking/03-spec-networking.md		 Unit 1 specifies NoNet/HostNet/OwnIp semantics, gvproxy lifecycle, per-PTask IP allocation, and proof artifacts. Unit 2 specifies egress allowlists, static/dynamic ingress port mappings with validation, VM-wide egress for DM1/DM3/DM4, a read-only policy RPC, and structured warn logging.
Unit 3 (DNS lifecycle) and Unit 4 (WireGuard/HTTPS remote connectivity)
docs/specs/03-spec-networking/03-spec-networking.md		 Unit 3 specifies DNS hostname registration/deregistration, rootless detection with warn remediation, and DNS tracing. Unit 4 specifies embedded WireGuard mesh lifecycle via CLI, HTTPS reverse proxy with mTLS/OIDC, topology-hiding auth failure logging, and feature-flag gating.
Non-goals, design rationale, repo standards, and open questions
docs/specs/03-spec-networking/03-spec-networking.md		 Documents explicit exclusions, rationale for one gvproxy per host, DNS mechanism options, wireguard-go vs boringtun considerations, repository/test standards, and async IO/TLS library selection checklist.
Security considerations and verification commands
docs/specs/03-spec-networking/03-spec-networking.md		 Defines socket permission expectations, default egress semantics, WireGuard revocation assumptions, HTTPS proxy auth boundary behavior, port <1024 refusal, opt-in exposure defaults, and the lint/build/test command matrix.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

Possibly related PRs

  • gominimal/minimal#479: Both PRs add new networking documentation specs describing the PTask/minimald networking stack (including gvproxy/DNS and remote browser connectivity paths), so they're related at the doc/content level.

Suggested reviewers

  • msample

Poem

🐇 Hoppity hop through the gvproxy lane,
Each PTask gets its own IP domain!
WireGuard mesh and DNS in tow,
Egress rules tell the packets where to go.
The spec is written, the plan is clear —
No root required, no secrets to fear! 🌐

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately and specifically summarizes the main change: adding a comprehensive minimald networking specification covering PTask network modes, DNS, egress/ingress policies, and WireGuard mesh.
Linked Issues check ✅ Passed The pull request fully addresses all seven use cases and core objectives from issue #481/#478: PTask network modes (UC1), DNS hostnames (UC2), egress policy (UC3), ingress port mappings (UC4), VM-wide egress (UC5), same-host PTask communication (UC6), and WireGuard mesh with SSH fallback (UC7).
Out of Scope Changes check ✅ Passed All changes are directly scoped to the minimald networking specification deliverable. The file adds comprehensive networking documentation with no extraneous modifications or unrelated changes.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

Comment @coderabbitai help to get the list of available commands and usage tips.

@gominimal-aw-bot

This comment has been minimized.

Sign in to view
@norrietaylor
norrietaylor commented Jun 20, 2026
Copy link
Copy Markdown
Member

/revise add DNS hostnames for host-net PTask services (UC2) and an SSH port-forward fallback for WireGuard-blocked networks; fix the RFC-6598 reference in R1.6

@gominimal-aw-bot
docs(spec-networking): add HostNet DNS, SSH fallback, fix RFC-6598 ref
0a59d39 
Add R3.6 for DNS hostname registration for HostNet PTasks (UC2);
hostnames resolve to 127.0.0.1 for local configs or the host's
network interface address for DM5.

Add R4.9 and a Design Considerations section for SSH port-forwarding
as a fallback remote-access transport for networks where WireGuard's
UDP is blocked; reuses the russh server already embedded for re-attach.

Fix R1.6: 100.64.0.0/16 is an RFC-6598 range, not RFC-5737.

Update Goals, User Stories, Unit 3 and Unit 4 Purpose, and proof
artifacts t
8000
o cover the two new requirements.

Refs #478
@gominimal-aw-bot
gominimal-aw-bot Bot commented Jun 20, 2026
Copy link
Copy Markdown
Contributor Author

Commit pushed: 0a59d39

Generated by sdd-spec

@gominimal-aw-bot
gominimal-aw-bot Bot commented Jun 20, 2026
Copy link
Copy Markdown
Contributor Author

sdd-validate findings — Spec boundary

Boundary resolved: Spec (docs/specs/03-spec-networking/03-spec-networking.md is a *-spec-*.md file under docs/specs/).
Gate set applied: Spec gates (5 gates).

Gate 1 — Acceptance criteria testable ✅ Pass

All functional requirements (R1.1–R4.9) are behavioral, observable pass/fail statements. Each unit's proof artifacts demonstrate the testable criteria directly.

Gate 2 — No implementation leakage ⚠️ Warning

R1.4 (docs/specs/03-spec-networking/03-spec-networking.md, line 138): prescribes a specific OS signal ordering (SIGTERM → timeout → SIGKILL) inside a functional requirement. The signal sequence is an implementation mechanism; a behavioral statement — e.g. "gvproxy is gracefully terminated when the last own-IP PTask exits" — would suffice at the spec level.

This is unchanged from the prior run; the revision did not introduce new leakage. Advisory — does not block advance.

Gate 3 — Assumptions explicit ✅ Pass

The Open Questions section explicitly flags the five unresolved decisions (DNS resolution mechanism, egress default policy, dynamic port-mapping API shape, WireGuard key exchange in v1, HTTPS proxy TLS cert management). Platform differences (DM2 vs DM1/3/4) and the UC5→UC3 collapse on native Linux are stated in Design Considerations.

Gate 4 — Proof artifacts present and behavioral ✅ Pass

All four units carry 2–3 proof artifacts each:

  • Unit 1: 2 integration tests (UC6 same-host PTask-to-PTask; UC1 no-net isolation)
  • Unit 2: 2 integration tests + 1 CLI (egress enforcement, ingress port mapping, policy RPC)
  • Unit 3: 1 integration test + 2 CLI (hostname lifecycle; UC2a local browser; UC2 HostNet hostname — new in this revision, R3.6)
  • Unit 4: 1 integration test + 2 CLI (UC7 remote mesh; UC2b mesh browser; SSH port-forward fallback — new in this revision, R4.9)

All artifacts are behavioral and would fail against an empty PR.

Gate 5 — Demoable units sized to reviewable PR ✅ Pass

The four units cover distinct, non-overlapping feature areas (gvproxy infrastructure and modes / policy enforcement / DNS hostname management / WireGuard mesh and SSH fallback). No unit appears under-sized relative to the 400-line floor with a cohesive sibling available to absorb it.

Summary

No Blockers. One Warning (R1.4 signal-sequence leakage, advisory). The spec boundary passes clean. The revision correctly adds R3.6 (HostNet PTask DNS) and R4.9 (SSH port-forward fallback) with matching proof artifacts, and corrects the RFC-6598 reference in R1.6.

Generated by sdd-validate for issue #482 · ◷

@norrietaylor
norrietaylor enabled auto-merge (squash) June 20, 2026 02:46
@norrietaylor
norrietaylor merged commit 5c17ece into main Jun 20, 2026
18 checks passed
@norrietaylor
norrietaylor deleted the spec/minimald-networking-13402276e247a84a branch June 20, 2026 02:46
This was referenced Jun 20, 2026
Merged
Merged
Merged
Merged
Merged
@gominimal-aw-bot gominimal-aw-bot Bot mentioned this pull request Jun 22, 2026
Closed
@coderabbitai coderabbitai Bot mentioned this pull request Jun 22, 2026
Merged
@gominimal-aw-bot gominimal-aw-bot Bot mentioned this pull request Jun 23, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@norrietaylor norrietaylor norrietaylor approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No mile 4601 stone

Development

Successfully merging this pull request may close these issues.

spec: minimald networking -- PTask network modes, DNS, egress/ingress, WireGuard mesh

1 participant

@norrietaylor
0