docs(spikes): restore dns-hostname-mechanism spike doc lost from main by norrietaylor · Pull Request #543 · gominimal/minimal

norrietaylor · 2026-06-23T14:09:58Z

The docs/spikes/2026-06-20-dns-hostname-mechanism.md spike (the *.localhost + host-proxy DNS decision) merged in #487 is missing from main — a later sdd-spec stale-base derivation reverted it (same class as norrietaylor/spectacles#317; cf. the #529 cleanup). #500 adopts this spike's finding, so the doc should be present.

Restored verbatim from the #487 merge commit 6cc2dde. Docs-only.

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation
- Updated hostname resolution format to .localhost with systemd-resolved configuration guidance for Linux distributions.

The 2026-06-20 DNS-hostname (*.localhost) spike merged in #487 is absent from main — a later sdd-spec stale-base derivation reverted it (the same class as norrietaylor/spectacles#317). Restore it verbatim from the #487 merge (6cc2dde); #500 adopts its *.localhost finding. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0143kv2BRrRqGxmVwwHskQtS

coderabbitai · 2026-06-23T14:10:45Z

📝 Walkthrough

Walkthrough

Adds docs/spikes/2026-06-20-dns-hostname-mechanism.md, a new spike document that evaluates wildcard *.localhost versus *.min.local DNS hostname resolution for rootless operation across Linux distributions and macOS, concludes in favor of *.localhost, specifies a startup probe with tracing::warn! remediation, and lists follow-on action items.

Changes

DNS Hostname Mechanism Spike

Layer / File(s)	Summary
Question, hypothesis, and empirical investigation `docs/spikes/2026-06-20-dns-hostname-mechanism.md`	Front-matter metadata is defined; the core question (`.localhost` vs `.min.local`) and hypothesis are stated; an Ubuntu/Docker sandbox probe records `NXDOMAIN` when `systemd-resolved` is inactive; per-distro resolver defaults are documented for Ubuntu, Fedora, Debian, Arch, and macOS; the `*.min.local` alternative is presented and rejected due to mDNS/Avahi conflicts and required root configuration.
Findings summary, startup probe, conclusion, and action items `docs/spikes/2026-06-20-dns-hostname-mechanism.md`	Key findings are summarized in a table including the systemd version floor for RFC 6761 synthesis and the libkrun VM note; the in-process startup probe design with `tracing::warn!` remediation is specified; the conclusion ("proved") recommends `<session-name>.<host-id>.localhost` with HTTP `Host:` routing; action items cover updating the R3.1 networking spec, Debian/Arch install docs, probe implementation, and an open in-VM DNS question; the full sandbox transcript and RFC/systemd-resolved reference sources are appended.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

gominimal/minimal#487: Modifies the same spike document (docs/spikes/2026-06-20-dns-hostname-mechanism.md), aligning on the *.localhost conclusion and .localhost hostname format.
gominimal/minimal#491: Deletes the same spike file this PR introduces, creating a direct conflict on docs/spikes/2026-06-20-dns-hostname-mechanism.md.

Poem

🐇 A hop through DNS, a trail of probes laid bare,
*.localhost blooms where NXDOMAIN filled the air.
systemd-resolved asleep? A warn! wakes it right,
.min.local rejected — mDNS put up a fight.
The spec is updated, the hostname path is clear,
This rabbit resolved it all, no root required here! 🌐

🚥 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 directly describes the main change: restoring a missing spike document about DNS hostname mechanism to the main branch.
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.

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

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 2

🤖 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-dns-hostname-mechanism.md`:
- Around line 242-246: Update the startup probe warning in the
dns-hostname-mechanism doc so the remediation includes the stub-resolver step as
well as enabling systemd-resolved. In the startup probe section that references
minimald-probe.localhost and tracing::warn!, make the remedy distro-aware or
mention both commands so Debian 12 and Arch users also repoint /etc/resolv.conf
to the systemd-resolved stub, ensuring *.localhost remains resolvable.
- Around line 48-54: The section claims that the Docker probe "faithfully
models" Debian 12 and Arch Linux behavior, but the empirical testing only
demonstrates one scenario (systemd-resolved inactive producing NXDOMAIN). Revise
the language at the point where "faithfully models" is used (around Finding A at
lines 90-95 and line 52) to distinguish between direct empirical observation and
documented defaults. Replace the broader modeling claim with more precise
language such as "This scenario (systemd-resolved inactive) matches the resolver
configuration defaults of Debian 12 and Arch Linux, which ship the binary but do
not enable the service" to ground the claim explicitly in the documented
evidence referenced later (lines 119-140) rather than implying the Docker
environment directly proves behavior on those distributions.

🪄 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: c12b408d-5a8b-4d89-b518-0f6f9ae3e346

📥 Commits

Reviewing files that changed from the base of the PR and between b239125 and a7bb59f.

📒 Files selected for processing (1)

docs/spikes/2026-06-20-dns-hostname-mechanism.md

msample · 2026-06-23T16:50:52Z

+Does `*.localhost` wildcard hostname resolution work rootlessly (no per-invocation
+root) on common Linux distributions targeted by `minimald` users — Ubuntu 22.04+,
+Fedora 38+, Debian 12 (stable), and Arch Linux? Or does the alternative
+`*.min.local` domain approach require a one-time resolver configuration step


*.min.internal may be better unless we are specifically hoping to integrate to mDNS/Bonjour?

Great catch and just in the nick of time.

The bot fleet had diverged from the spec.

Claude says

The networking spec's plan is R5 "PTask hostnames in host DNS" → B5 "*.localhost + host-side proxy (or one-time /etc/resolver)" (plus a named gvproxy-webproxy + macOS PAC-file path), tagged "Needs decision (DNS) — zero-root path exists".
The load-bearing piece is the host-side proxy doing hostname→PTask routing, with resolution host-side — so it's systemd-agnostic (our sandboxes and microVMs have no systemd, and per the spec they never need to resolve anything; the host does). The TLD (.localhost vs .min.internal) is then just proxy/resolver config, not the mechanism.
We diverged in #500/#546 by narrowing B5 down to a systemd-resolved probe (R3.4), which both drops the host-side proxy and breaks in the no-systemd runtime. Re-aligning #500 to the spec's B5 host-side-proxy model — .min.internal is fully viable under it if preferred.

Proceeding on same-component: #500 lands net/proxy.rs as the routing core and #502 extends it with TLS/mTLS — one proxy, not two. Defaulting client→proxy to proxy-env/PAC (zero-root, cross-platform); shout if you want /etc/resolver instead. Re-aligning #546 to this now.

Adopting .min.internal per your call. Under the B5 host-side egress proxy the TLD is a free label (proxy routes by Host: header, no resolver), so no mDNS/Bonjour tie-in — .min.internal is the cleaner, semantically-honest choice for internal PTask services. Swapping it across the proxy/registry/tests/spec in #546 now.

bryan-minimal

LGTM

norrietaylor · 2026-06-23T19:52:35Z

__

norrietaylor mentioned this pull request Jun 23, 2026

epic: minimald networking — PTask network modes, DNS, egress/ingress, WireGuard mesh #478

Closed

coderabbitai Bot reviewed Jun 23, 2026

View reviewed changes

Comment thread docs/spikes/2026-06-20-dns-hostname-mechanism.md

Comment thread docs/spikes/2026-06-20-dns-hostname-mechanism.md

msample reviewed Jun 23, 2026

View reviewed changes

bryan-minimal approved these changes Jun 23, 2026

View reviewed changes

norrietaylor closed this Jun 23, 2026

norrietaylor deleted the restore/dns-spike-doc branch June 26, 2026 07:16

Navigation Menu

Uh oh!

docs(spikes): restore dns-hostname-mechanism spike doc lost from main - #543

docs(spikes): restore dns-hostname-mechanism spike doc lost from main#543
norrietaylor wants to merge 1 commit into
mainfrom
restore/dns-spike-doc

norrietaylor commented Jun 23, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 23, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

msample Jun 23, 2026

Uh oh!

norrietaylor Jun 23, 2026 •

edited

Loading

Uh oh!

norrietaylor Jun 23, 2026

Uh oh!

norrietaylor Jun 23, 2026

Uh oh!

bryan-minimal left a comment

Uh oh!

norrietaylor commented Jun 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

norrietaylor commented Jun 23, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

msample Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

norrietaylor Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

norrietaylor Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

norrietaylor Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

bryan-minimal left a comment

Choose a reason for hiding this comment

Uh oh!

norrietaylor commented Jun 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

norrietaylor commented Jun 23, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 23, 2026 •

edited

Loading

norrietaylor Jun 23, 2026 •

edited

Loading