Skip to content

docs(networking): added a docs/spec for networking - #479

Merged
msample merged 1 commit into
mainfrom
mike/networking-spec
Jun 19, 2026
Merged

msample merged 1 commit into
mainfrom
mike/networking-spec

Conversation

@msample

@msample msample commented Jun 19, 2026 •

Copy link
Copy Markdown
Member

Summary by CodeRabbit

Documentation

  • Added comprehensive networking specification guide with diagrams, covering deployment models, networking use cases, and implementation approaches for different connectivity scenarios.

@coderabbitai

coderabbitai Bot commented Jun 19, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

A new documentation file docs/specs/03-spec-networking/networking-with-diagrams.md is added. It defines the Minimal networking domain model (Host, PTask, minimald), supported deployment models, use cases UC1–UC7, a rootless implementation analysis mapping requirements to building blocks, a network topology section, and UC2b remote browser access implementation notes, all illustrated with Mermaid diagrams.

Changes

Networking Specification Document

Layer / File(s) Summary
Domain model and deployment models
docs/specs/03-spec-networking/networking-with-diagrams.md
Introduces document header and definitions for Host, PTask, and minimald; enumerates deployment models (MacOS+libkrun+gvproxy, native Linux single/host+VM, network-exposed minimald) with Mermaid diagrams for component relationships and deployment variants.
Use case access flows (UC1–UC7)
docs/specs/03-spec-networking/networking-with-diagrams.md
Defines UC2 hostname/DNS access flows (local browser, remote browser via WireGuard mesh option A and HTTPS reverse proxy option B), UC6/UC7 PTask-to-PTask connectivity diagrams, and UC1/UC3/UC4/UC5 ingress/egress policy diagram.
Rootless implementation analysis and network topology
docs/specs/03-spec-networking/networking-with-diagrams.md
Maps requirements to rootless building blocks (user namespaces/tap, gvproxy, hostname resolver, WireGuard/tailscale userspace netstack, libkrun, minimald HTTPS reverse proxy) with a privilege-categorized diagram; adds Network Topology (Shape 2) section covering MacOS VM and native Linux host traffic flows through gvproxy/minimald.
UC2b remote browser access implementation notes
docs/specs/03-spec-networking/networking-with-diagrams.md
Describes WireGuard mesh option (raw TCP/UDP) and HTTPS reverse proxy on minimald with mTLS/OIDC option (HTTP/WebSockets only), with diagram change rationale and SSH port-forwarding fallback justification.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Possibly related issues

  • epic: minimald networking — PTask network modes, DNS, egress/ingress, WireGuard mesh #478: This PR implements the networking specification documentation referenced by that epic, covering the same UC1–UC7 use cases, libkrun/gvproxy/WireGuard/minimald architecture, and rootless deployment models.
  • gominimal/inbox#245: This PR directly adds the networking spec documentation matching the requirements outlined in that issue, including UC1–UC7 use cases, deployment models, rootless implementation approaches, and UC2b access options.

Suggested reviewers

  • norrietaylor

Poem

🐇 A spec hopped in, diagrams in paw,
With gvproxy flows and WireGuard's draw,
UC2b options, A and B,
Rootless tunnels running free,
The mesh is set, the proxy gleams—
Now every PTask talks in streams! 🌐

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title 'docs(networking): added a docs/spec for networking' accurately reflects the main change: adding a new networking documentation specification file.

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

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

🤖 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/specs/03-spec-networking/networking-with-diagrams.md`:
- Around line 14-16: Replace all instances of "MacOS" with "macOS" throughout
the networking documentation file to match Apple's official product naming
convention which uses a lowercase "m". Use a find-and-replace operation to
systematically update all occurrences consistently across the entire document,
ensuring brand accuracy and professionalism in the technical specification.
- Line 46: Fix the spelling error in the phrase containing "could even supoprt
file synchronization to the re-attaching" by replacing the misspelled word
"supoprt" with the correct spelling "support".
- Line 6: The word "exlude" contains a spelling error and should be corrected to
"exclude". Locate the occurrence of "exlude" in the networking-with-diagrams.md
file and replace it with the correctly spelled "exclude" to fix the typo.
- Line 3: Correct the spelling error in the document title line where it reads
"This specificaiton outlines the networking use cases for the Minimal "minimald"
tool." Change "specificaiton" to "specification" to fix the typo.
- Line 47: In the networking-with-diagrams.md file, locate the phrase "different
than" on line 47 and replace it with "different from" to maintain formal
documentation standards and proper grammar.
🪄 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: 3fd85634-ad17-4071-afdf-abcc3f30a483

📥 Commits

Reviewing files that changed from the base of the PR and between eaca741 and 9c3f733.

📒 Files selected for processing (1)
  • docs/specs/03-spec-networking/networking-with-diagrams.md

@@ -0,0 +1,642 @@
# Networking in Minimal — Spec with Diagrams

This specificaiton outlines the networking use cases for the Minimal "minimald" tool.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix spelling error in document title.

Line 3 has a typo: "specificaiton" should be "specification."

-This specificaiton outlines the networking use cases for the Minimal "minimald" tool.
+This specification outlines the networking use cases for the Minimal "minimald" tool.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
This specificaiton outlines the networking use cases for the Minimal "minimald" tool.
This specification outlines the networking use cases for the Minimal "minimald" tool.
🤖 Prompt for 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.

In `@docs/specs/03-spec-networking/networking-with-diagrams.md` at line 3, Correct
the spelling error in the document title line where it reads "This specificaiton
outlines the networking use cases for the Minimal "minimald" tool." Change
"specificaiton" to "specification" to fix the typo.

This specificaiton outlines the networking use cases for the Minimal "minimald" tool.

The is some exploration of implementation options that do not require the user
to have root privileges. This does not exlude other implementation approaches or

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix spelling error: "exlude" → "exclude".

Line 6 contains a typo in "exlude" which should be "exclude."

-to have root privileges. This does not exlude other implementation approaches or
+to have root privileges. This does not exclude other implementation approaches or
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
to have root privileges. This does not exlude other implementation approaches or
to have root privileges. This does not exclude other implementation approaches or
🧰 Tools
🪛 LanguageTool

[grammar] ~6-~6: Ensure spelling is correct
Context: ... to have root privileges. This does not exlude other implementation approaches or addi...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🤖 Prompt for 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.

In `@docs/specs/03-spec-networking/networking-with-diagrams.md` at line 6, The
word "exlude" contains a spelling error and should be corrected to "exclude".
Locate the occurrence of "exlude" in the networking-with-diagrams.md file and
replace it with the correctly spelled "exclude" to fix the typo.

Comment on lines +14 to +16
The implementation choices are **libkrun** for MacOS Linux VMs, **one gvproxy
per host** serving all PTasks as switch clients (over `unix socket` on native
Linux, over `vsock` through the libkrun VM on MacOS), a **WireGuard mesh** with

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Standardize Apple operating system naming: "MacOS" → "macOS".

The official Apple product name uses lowercase "m": macOS. The document currently uses "MacOS" inconsistently. Please replace all instances of "MacOS" with "macOS" throughout the document for brand consistency and professionalism. This affects approximately 13+ occurrences across lines 14, 16, 27, 114, 171, 387, 392, 400, 405, 412, 482, 485, 491, and 579.

Example corrections:

  • Line 14: "for libkrun for MacOS Linux VMs" → "for libkrun for macOS Linux VMs"
  • Line 27: "The OS can be MacOS and Linux" → "The OS can be macOS and Linux"
  • Line 387: "on Hypervisor.framework on MacOS" → "on Hypervisor.framework on macOS"

Also applies to: 27-27, 114-114, 171-171, 387-387, 392-392, 405-405, 412-412, 482-482, 485-485, 491-491, 579-579

🧰 Tools
🪛 LanguageTool

[uncategorized] ~14-~14: The operating system from Apple is written “macOS”.
Context: ...lementation choices are libkrun for MacOS Linux VMs, one gvproxy per host ser...

(MAC_OS)


[uncategorized] ~16-~16: The operating system from Apple is written “macOS”.
Context: ... over vsock through the libkrun VM on MacOS), a WireGuard mesh with minimald as...

(MAC_OS)

🤖 Prompt for 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.

In `@docs/specs/03-spec-networking/networking-with-diagrams.md` around lines 14 -
16, Replace all instances of "MacOS" with "macOS" throughout the networking
documentation file to match Apple's official product naming convention which
uses a lowercase "m". Use a find-and-replace operation to systematically update
all occurrences consistently across the entire document, ensuring brand accuracy
and professionalism in the technical specification.


In the future there may be bi-directional file synchronization options
between the invocation environment and the PTask. Interactive PTasks
could even supoprt file synchronization to the re-attaching

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix spelling error: "supoprt" → "support".

Line 46 contains a typo: "supoprt" should be "support."

-could even supoprt file synchronization to the re-attaching
+could even support file synchronization to the re-attaching
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
could even supoprt file synchronization to the re-attaching
could even support file synchronization to the re-attaching
🤖 Prompt for 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.

In `@docs/specs/03-spec-networking/networking-with-diagrams.md` at line 46, Fix
the spelling error in the phrase containing "could even supoprt file
synchronization to the re-attaching" by replacing the misspelled word "supoprt"
with the correct spelling "support".

In the future there may be bi-directional file synchronization options
between the invocation environment and the PTask. Interactive PTasks
could even supoprt file synchronization to the re-attaching
environment, which might be different than the original invocation

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Correct grammar: "different than" → "different from".

Line 47 uses colloquial style "different than" which should be "different from" in formal documentation.

-be kept after the PTask is terminated will be pushed out over the network (e.g. to github).
+be kept after the PTask is terminated will be pushed out over the network (e.g. to GitHub).
🧰 Tools
🪛 LanguageTool

[style] ~47-~47: Did you mean ‘different from’? ‘Different than’ is often considered colloquial style.
Context: ...g environment, which might be different than the original invocation environment. Un...

(DIFFERENT_THAN)

🤖 Prompt for 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.

In `@docs/specs/03-spec-networking/networking-with-diagrams.md` at line 47, In the
networking-with-diagrams.md file, locate the phrase "different than" on line 47
and replace it with "different from" to maintain formal documentation standards
and proper grammar.

@msample msample changed the title feature: added a docs/spec for networking feat: added a docs/spec for networking Jun 19, 2026
@msample msample changed the title feat: added a docs/spec for networking docs(networking): added a docs/spec for networking Jun 19, 2026
@msample
msample merged commit 3495140 into main Jun 19, 2026
131 of 132 checks passed
@msample
msample deleted the mike/networking-spec branch June 19, 2026 22:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants