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:
@@ -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
|
||||
|
||||
@@ -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 |
|
||||
|
||||
Reference in New Issue
Block a user