Give the own resolver's file a wait longer than its pass over a silent mesh resolver

ADR 0678: on a machine holding node-resolver the file names the own resolver
alone, so a program gave up after about 2 s while resolved still waited on a
silent first mesh resolver (issue 1748). Design 50 section 2 now gives the
file timeout:3 attempts:2 and how the value follows the measured pass; the
new milestone part resolver-wait holds the lines that build it, putting the
design in the shape of a main file and milestone parts.
This commit is contained in:
2026-11-12 18:05:05 +01:00
parent 0d04a16560
commit 067de23181
3 changed files with 97 additions and 12 deletions
@@ -0,0 +1,63 @@
---
layer: to-be
design: 50
milestone: resolver-wait
updated: 2026-11-12
code: [mesh-catalog modules/systemd-resolved, mesh-host internal/compose/resolution]
decisions:
- "ADR 0678"
- "ADR 0247"
- "ADR 0223"
---
# Design 50, milestone resolver-wait — the own resolver's file waits longer than its pass
**What it builds.** On a machine where a module holds the node seat `node-resolver`, the file `/etc/resolv.conf`
gives its programs a wait longer than the own resolver's pass over one silent mesh resolver to the next, so a lookup
behind a silent first mesh resolver answers late instead of failing (ADR 0678 §1). The value is the main file's,
[§2](../50-split-dns-on-a-machine-with-a-vpn-client.md#2-the-file-and-the-resolver):
`options timeout:3 attempts:2 edns0`. This part holds every line the milestone builds, cited as "design 50 resolver-wait §n". It is built under
issue 1748.
**Where.** Two repositories: mesh-catalog (the module `systemd-resolved`, holder of `node-resolver`: §1) and `mesh-host`
(the node-engine's names check and its test: §3). One milestone, its two pull requests one delivery group with one
check. No ordering edge joins them: once §3's test reads the options from the catalog's template, each repository's
check passes against the other's main, whichever merges first.
## Lines
1. **The own resolver's template carries the longer options.** The module `systemd-resolved` renders the file twice
from one template, its facts `resolvers` (the live file) and `kept` (the kept copy beside resolved's
configuration, which the guard puts back); both carry the options line of design 50 §2, `options timeout:3
attempts:2 edns0`, in place of `options timeout:1 attempts:2 edns0`, which goes from the template. The one
`nameserver` line, the machine's private address, is unchanged. The node-engine writes both when it renders the
module, the kept copy first (design 50, *As built*), so the guard never compares a new live file with an old copy.
Read by `<node>/node-reads.read` of the file and by the uplink seat's `resolvers` verb, as today. Checked by the
module's manifest test, which asserts the one server and this options line in both facts; the guard's own test,
which holds a literal of the file, carries the new line.
2. **Nothing else of the resolver changes** (ADR 0678 §2). resolved's drop-in stays as it is: no cache, the mesh's
resolvers as its servers in the order of the module's roster (ADR 0223 §9), `~.`, no fallback, its extra listener
on the private address. The uplink modules' files (`networkmanager`, `systemd-networkd`) keep both mesh resolvers
with `timeout:1 attempts:2`, held by the existing test over every uplink's resolver file. The captured copies of
the catalog in other repositories' test data are left as they are: no check reads them.
3. **The names check judges the file with the wait its programs give it.** The node-engine's names check already
bounds each ask by the `timeout:` of the file it judges, never under 1 s; that stays, so on a machine holding
`node-resolver` each ask's bound becomes 3 s. Its test that composes the catalog's own resolver on a machine
reads the expected options line from the catalog's `systemd-resolved` template beside it, in place of the literal
`timeout:1 attempts:2 edns0` it asserts today (ADR 0678, *How it is checked*). The reason: a test literal of
another repository's template fails one repository's check on whichever merges first, the kind issue 1748's note
of 2026-11-10 met.
4. **The pass is measured, and the value follows it.** After the delivery, on the workstation first and then the
laptop: `<node>/node-reads.read` of `/etc/resolv.conf` shows the one server and §1's line. At the next time the
machine's first mesh resolver is silent (its machine unreachable, raised in `mesh-conditions.conditions`), the
worker of issue 1748 restarts resolved with `<node>/node-service-manager.restart` and at once asks a mesh name with
`<node>/netcheck.netcheck_dns`, `server` the machine's private address and `timeout_ms` 30000; the time it answers
in is the pass. The restart comes first because resolved keeps asking the server it passed to, so only the first
lookup after it starts meets the pass (the 42 ms answer read on 2026-11-12 with the first mesh resolver silent);
the machine has no names for the moment of the restart. A pass under 6 s leaves design 50 §2 as it is; a pass of
6 s or more raises §2's timeout to the next whole second above the pass, the attempts staying two, and §1 is
delivered again. The measured time is written on issue 1748 as a note by its worker.
5. **The live proof.** At the next silence of the first mesh resolver, `mesh-build-go.build_go_steps` lists no Go
build step on a machine holding `node-resolver` failed with `i/o timeout` at that machine's own address. Issue
1748 is resolved once §4's read of the file holds, naming this line as where the proof will show, and reopened
if it fails.
@@ -6,11 +6,13 @@ code:
- mesh-controller internal/catalogue/seats.go, declaration.go, resolve.go
- mesh-catalog modules/systemd-resolved (the resolver, its guard and its verbs)
- mesh-catalog modules/forticlient (the VPN client's adapter)
updated: 2026-10-07
- mesh-host internal/compose/resolution, internal/network (the names check of the file, milestone resolver-wait)
updated: 2026-11-12
decisions:
- "ADR 0247"
- "ADR 0223"
- "ADR 0241"
- "ADR 0678"
---
# 50 — Split DNS on a machine with a VPN client
@@ -66,8 +68,15 @@ not share a machine.
## 2. The file and the resolver
- **The file** names the machine's private address alone, with ADR 0223's options, and begins as every
mesh resolver file does, so the uplink's `resolvers` verb and the node-engine read it as the mesh's.
- **The file** names the machine's private address alone and begins as every mesh resolver file does, so
the uplink's `resolvers` verb and the node-engine read it as the mesh's.
- **The file's options wait longer than resolved's pass** over one silent mesh resolver to the next
(ADR 0678 §1): `options timeout:3 attempts:2 edns0`, a total wait of 6 s, the timeout times the attempts, where
ADR 0223's `timeout:1 attempts:2` gave about 2 s. Its program asks only the own resolver, so it waits on that
pass; a file that lists the mesh's resolvers keeps `timeout:1 attempts:2`, because its programs try the second
after one second (ADR 0678 §2, design 08 §2). The value holds while the pass, measured on such a machine with its
first mesh resolver silent, is shorter than the total; a pass of 6 s or more raises the timeout by whole seconds,
in this line, the attempts staying two as design 08 §2 gives every file (milestone resolver-wait §4).
- **The uplink's holder steps back** from that path on that machine, by the controller's rule. It does not
write the file and lose a race; it is never given the file to write.
- **resolved** is given every mesh resolver as its global servers, with `~.` so they answer every name no
@@ -122,24 +131,37 @@ resolver's hold, and is therefore raised. A VPN that tells resolved its link's D
## 6. What it costs and what it does not do
- The client's search domains route full names. They do not complete short ones.
- A name no mesh resolver answers takes the file's total wait to fail on that machine: 6 s, about 4 s longer
than before (ADR 0678).
- resolved down is no names on that machine. Its `unit` health, and the node-engine's names check against
the address the file lists, say so.
- resolved should take no servers from the resolver file, because its own are configured. The live test
confirms this while a write stands.
- A container started before the resolver keeps the mesh's two resolvers until it restarts.
## Phases
## How it is checked
| Phase | Repository | Delivers | Done when |
|---|---|---|---|
| A — the seat | mesh-controller | `node-resolver` and its verbs; the uplink stepping back | its tests pass; the controller is running on the mesh |
| B — the resolver | mesh-catalog `systemd-resolved` | the module, its guard and verbs | its tests pass; assigned to every machine that runs the VPN client's module, each one's file names its own address, `routes` answers |
| C — the adapter | mesh-catalog `forticlient` | `split-dns` required; the adapter | its tests pass; on the laptop, connected, a company name and a mesh name both resolve and no rewrite stays raised |
| Check | Defends |
|---|---|
| the own resolver module's manifest test: its file names one server, the machine's private address, with §2's options | ADR 0247 §6, ADR 0678 §1 |
| the node-engine's test that composes the catalog's own resolver on a machine reads the options from the catalog's template, not a literal, and its names check bounds each ask by the file's `timeout:` | ADR 0678 §1 |
| the test over every uplink's resolver file: both mesh resolvers, `timeout:1 attempts:2` | ADR 0678 §2, design 08 §2 |
| live, on a machine holding `node-resolver` with its first mesh resolver silent: a timed lookup at the own resolver answers within the file's total wait; at the next silence no Go build step there fails on `i/o timeout` | ADR 0678 §1 |
| each phase's *Done when* below | ADR 0247 |
## Milestones
| Milestone | Repository | Delivers | Done when | State |
|---|---|---|---|---|
| A — the seat | mesh-controller | `node-resolver` and its verbs; the uplink stepping back | its tests pass; the controller is running on the mesh | running: the seat is held on the laptop and the workstation (read 2026-11-12, issue 1748); no as-is design yet |
| B — the resolver | mesh-catalog `systemd-resolved` | the module, its guard and verbs | its tests pass; assigned to every machine that runs the VPN client's module, each one's file names its own address, `routes` answers | running: each holder's file names its own address and `routes` answers (read 2026-11-12, issue 1748) |
| C — the adapter | mesh-catalog `forticlient` | `split-dns` required; the adapter | its tests pass; on the laptop, connected, a company name and a mesh name both resolve and no rewrite stays raised | running: the adapter's service runs beside the resolver on the workstation (issue 1748, 2026-11-10); its connected test is not recorded here |
| resolver-wait | mesh-catalog `systemd-resolved`, `mesh-host` | §2's options (ADR 0678), under issue 1748 | the live check above | designed; its part is [`50-milestones/resolver-wait.md`](50-milestones/resolver-wait.md) |
## As built
One pull request in mesh-controller (phase A), and two in mesh-catalog (B, then C on top of it). None is
merged. What the build chose where ADR 0247 left it open:
One pull request in mesh-controller (phase A), and two in mesh-catalog (B, then C on top of it). What the
build chose where ADR 0247 left it open:
- **The kept copy.** The mesh renders the module's file twice, at `/etc/resolv.conf` and beside resolved's
configuration. The guard compares the live file with the copy and puts the copy back, so it needs nothing
+1 -1
View File
@@ -49,7 +49,7 @@ document is written and this one's status becomes `implemented`.
| [`46-the-conversation-with-the-operator.md`](46-the-conversation-with-the-operator.md) | **Designed.** The mesh tells and asks its operator over channels that are holders of two kinded benches, `channel` and `intake`, declaring capabilities from a fixed vocabulary; the router orders them by work context and never lowers the bar; an answer that performs an action is checked and performed by the controller, on a TOTP code or a verified Telegram sender, never on a desk click alone; operator messages addressed or answered by the mesh's responder, untrusted input kept as data, references for what words may not carry, and a recoverable factor; Telegram first, in six phases | ADR 0234, ADR 0227 |
| [`47-delivery-from-commit-to-delivered.md`](47-delivery-from-commit-to-delivered.md) | **Designed.** A delivery is one commit in one repository, from its pull request's head to every machine; a delivery group is deliveries sharing a branch name, ordered and checked as one future state; both owned by the `mesh-delivery` module with one state table, its state on the bus, every transition said, noted on the commit and shown on the pull request; the controller keeps the planner, the gate, sending and the rollout, and the core's own updates never wait for the module | ADR 0239, ADR 0238, ADR 0236 |
| [`49-the-mesh-in-domains.md`](49-the-mesh-in-domains.md) | **In progress.** Every concept belongs to one of eleven domains, which owns its one word; the glossary is organised by them and is the authority, a retired word is named on its replacement's line with its scope, and two checks hold this repository's documents and the catalog's tool descriptions to it | ADR 0244, ADR 0006, ADR 0008, ADR 0302 |
| [`50-split-dns-on-a-machine-with-a-vpn-client.md`](50-split-dns-on-a-machine-with-a-vpn-client.md) | **In progress.** A machine whose VPN client pushes servers of its own runs a resolver of its own, on a node seat, that routes the VPN's domains over its link and every other name to the mesh's resolvers; the VPN client's module carries the adapter | ADR 0247, ADR 0223 |
| [`50-split-dns-on-a-machine-with-a-vpn-client.md`](50-split-dns-on-a-machine-with-a-vpn-client.md) | **In progress.** A machine whose VPN client pushes servers of its own runs a resolver of its own, on a node seat, that routes the VPN's domains over its link and every other name to the mesh's resolvers; the VPN client's module carries the adapter | ADR 0247, ADR 0223, ADR 0678 |
| [`51-the-registries-keep-what-is-named.md`](51-the-registries-keep-what-is-named.md) | **In progress.** The artifact store, the package registry and each machine's container runtime get tools that say what they hold, what names each thing and what could go; every removal is a dry run unless a person asks and says why, and what decides is always a record | ADR 0251, ADR 0189 |
| [`52-shares-and-mounts.md`](52-shares-and-mounts.md) | **In progress.** A node shares one folder at a time through `nfs-server`, which provides it as a provision to the private network only, mapping every client to the folder's owner; a node that asks mounts it through `mounts`, a mount unit and an automount per share, so nothing mounts or fails at boot; a device that comes and goes is an occasional source whose absence is a state | ADR 0263, ADR 0051, ADR 0092 |
| [`53-the-issue-tracker.md`](53-the-issue-tracker.md) | **Designed.** The mesh keeps its issues in one module, `issues`, on the control-node: every number from one counter advanced by compare-and-set, the cycle's issue rules refused at the write, an event per change; an issue lives whole in the tracker, hq keeping no issue content (ADR 0291) | ADR 0275, ADR 0291 |