Skip to content

feat(relay): relay-peer-names writes every peer's owner, and says when it could not ask - #977

Open
dlf-dds wants to merge 2 commits into
mainfrom
feat/relay-peer-names-owner
Open

dlf-dds wants to merge 2 commits into
mainfrom
feat/relay-peer-names-owner

Conversation

@dlf-dds

@dlf-dds dlf-dds commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

Why

relay-peer-names writes peer-names.json on the management host every 5 minutes. The relay-health dashboard reads it, and the topology surface will too. It had two defects.

It asked the portal only about peer- names. Machines and infrastructure peers were never resolved.

A refused key left no trace. When the portal refused its key, it logged one line and wrote the file with no owner fields and no marker, and the timer still succeeded. A refused key therefore read as "no owner" everywhere. On one goatnet, peerview's copy of that key drifted from the portal's and is refused (HTTP 401). The writer's own key was found accepted there. The portal's guard compares only the handle map, never the root key, so nothing at deploy time catches either drift.

What changes

  • relay-peer-names.py:
    • asks about every peer in one batch;
    • writes the resolver's owner block on each card. The block holds the source (record, roster, none), the organization and its nation, the responsible person's handle and identity id, and the person's own nationality, each with a state. It carries no e-mail or display name. ory_id is kept as before;
    • when the portal cannot be asked (no key on the host, refused, unreachable), writes owner: {source: "unread", reason} on every card and owner_read: {state, reason, at} in the file.
  • ops/identity/peerowner.py: every row carries owner (owner_block()). A portal older than the record resolver has its answers labeled source: "roster", so a consumer never reads a roster answer as the record. UNREAD rows carry owner.source: "unread".
  • relay-health role: the deploy now fails when the portal refuses the key the writer will present (tasks/assert-portal-key-accepted.yml, as panoscope, flashlight and stethoscope already do). It resolves the portal app's address the same way the writer does (relay_peer_names_portal_url, else the container IP on its docker network). On a goatnet whose writer key is stale, the relay-health deploy fails here until the key is re-rendered. That is the point of the check. It changes nothing on a running host, because the play stops before writing anything. On the goatnet measured, the writer's key is accepted, so the check passes there.
  • Design: docs/design/peer-identity-resolution.md §"The carrier to the host surfaces" is marked built.

What changes on a host after deploy:

  • A machine- card's ory_id and dashboard link now point at the machine's recorded custodian, because the custodian is the person answerable for the machine.
  • Cards of names that carry no owner get owner.source: "none" with the reason.

Proof

  • ops/relay/health/test_relay_peer_names_owner.py, synthetic names. It checks that:
    • every peer is asked about, machines and infrastructure included;
    • the owner block lands on each card without the e-mail;
    • a refused key is unread on every card and in the file, and an absent key is unread, not silent;
    • an older portal's answers are labeled roster;
    • the file carries owner_read.
  • ops/identity/test_peerowner.py (13 tests) still passes. Both now run in goat-obs-checks.yml.
  • py_compile passes. The role tasks were rendered with jinja2 for all three URL cases. check-role-template-refs-resolve.sh passes (257 references). Identity spillage and bash portability are ok. check-doc-links.py: 0 broken. Leak gate on the changed files: 0 hits. Embargo scan: clean.

@dlf-dds
dlf-dds requested a review from a team as a code owner November 16, 2026 10:25
Base automatically changed from feat/portal-peer-owner-from-record to main November 16, 2026 10:41
dlf-dds added a commit that referenced this pull request Nov 16, 2026
…he owner state only

Review of #977 (eleven items) and item 1 of the reconcile review.

- The portal's batch answer says machine-readably when a layer the owner
  tiers read did not answer (owner_sources {ok, failed}: registry, slot
  aliases, machines, identity layer) and marks every row's owner unread.
- peerowner.py never raises: a body that is not a peers map, a non-dict row
  or a client error is unread; a portal older than the owner block, or an
  owner block without a source, is unread, not "none"; names go in chunks of
  500 under the portal's request cap.
- relay-peer-names grades the cycle unread when every card is unread, and
  survives a client exception as an unread cycle.
- The cloud relay-health box gets the names it had plus the owner state
  (source, exception) and the file-level owner_read and generated_at, in a
  reserved key an older ingest stores harmlessly and the ingest now lifts;
  no person, identity id, organization or nationality leaves the host. An
  over-cap or refused cloud body exits non-zero after the on-host write.
- The deploy proves the key on the operator route the writer uses (POST
  /api/access/peers); only a refused key fails it; a portal that is down or
  not found warns and the health dashboard still deploys; the writer
  enabled with no key fails unless relay_peer_names_owner_enabled is false.
- Comments and the design say rules, not observations of a goatnet.

Each item has a test that fails on the previous head.

Signed-off-by: dlf-dds <dene.farrell.gov@gmail.com>
return hits[0]

def test_the_probe_asks_the_operator_route_the_writer_uses(self):
self.assertNotIn("assert-portal-key-accepted", open(TASKS).read(),
dlf-dds added a commit that referenced this pull request Nov 16, 2026
…what it could not apply

Review of feat/peer-owner-reconcile, items 2 to 12 (item 1 is in #977).

- --write-exceptions runs as documented (argparse fixed) and needs
  --granted-on YYYY-MM-DD from the operator; it opens the file with
  exclusive create; --check-exceptions checks a file against the schema.
- An unread cycle writes no fresh count: it carries the last read cycle's
  counts and their read time, so a failed lookup neither clears nor raises
  PeerOwnerUnrecorded. Shipped promtool case 2 asserted unrecorded 0 on an
  unread cycle; it now asserts the page stays up on the carried count.
- The loader enforces the schema and never raises: a malformed file is not
  loaded; an entry with a missing field, a bad date or an unknown key is
  refused; a repeated peer id refuses both. New metrics say whether the file
  was configured and loaded and how many entries were refused.
- Rules keep the instance label (two writers page once each, with their own
  count) and add PeerOwnerMetricsAbsent, PeerOwnerPartlyUnread and
  PeerOwnerExceptionsNotLoaded.
- The deploy validates the overlay's file before it lands, removes a host
  file the overlay no longer has, and the seed run gets the timer's
  environment.
- peer_gone and partly unread names are logged.

Each item has a test that fails on the previous head; the new CLI test runs
the real program against a fake NetBird store and a fake portal.

Signed-off-by: dlf-dds <dene.farrell.gov@gmail.com>
…n it could not ask

relay-peer-names asked the portal only about peer- names and, when the
portal refused its key, wrote peer-names.json with no owner fields and no
marker while the timer succeeded. A refused key therefore read as "no owner"
on every surface that reads the file.

It now asks about every peer in one batch (machines and infrastructure
included) and writes the resolver's owner block on each card: source (record,
roster, none), how the first hop matched, the organization and its nation,
the responsible person's handle and identity id, the person's own
nationality, each with a state; no e-mail or display name. When the portal
cannot be asked, every card carries owner {source: unread, reason} and the
file carries owner_read. The shared client ops/identity/peerowner.py carries
the block, labeling an older portal's answers as roster. The relay-health
deploy now fails when the portal refuses the writer's key
(assert-portal-key-accepted.yml), as panoscope's does. Unit tests run in
goat-obs-checks.

Signed-off-by: dlf-dds <dene.farrell.gov@gmail.com>
…he owner state only

Review of #977 (eleven items) and item 1 of the reconcile review.

- The portal's batch answer says machine-readably when a layer the owner
  tiers read did not answer (owner_sources {ok, failed}: registry, slot
  aliases, machines, identity layer) and marks every row's owner unread.
- peerowner.py never raises: a body that is not a peers map, a non-dict row
  or a client error is unread; a portal older than the owner block, or an
  owner block without a source, is unread, not "none"; names go in chunks of
  500 under the portal's request cap.
- relay-peer-names grades the cycle unread when every card is unread, and
  survives a client exception as an unread cycle.
- The cloud relay-health box gets the names it had plus the owner state
  (source, exception) and the file-level owner_read and generated_at, in a
  reserved key an older ingest stores harmlessly and the ingest now lifts;
  no person, identity id, organization or nationality leaves the host. An
  over-cap or refused cloud body exits non-zero after the on-host write.
- The deploy proves the key on the operator route the writer uses (POST
  /api/access/peers); only a refused key fails it; a portal that is down or
  not found warns and the health dashboard still deploys; the writer
  enabled with no key fails unless relay_peer_names_owner_enabled is false.
- Comments and the design say rules, not observations of a goatnet.

Each item has a test that fails on the previous head.

Signed-off-by: dlf-dds <dene.farrell.gov@gmail.com>
@dlf-dds
dlf-dds force-pushed the feat/relay-peer-names-owner branch from 2f3155e to 5ea8c3a Compare November 16, 2026 12:44
dlf-dds added a commit that referenced this pull request Nov 16, 2026
…what it could not apply

Review of feat/peer-owner-reconcile, items 2 to 12 (item 1 is in #977).

- --write-exceptions runs as documented (argparse fixed) and needs
  --granted-on YYYY-MM-DD from the operator; it opens the file with
  exclusive create; --check-exceptions checks a file against the schema.
- An unread cycle writes no fresh count: it carries the last read cycle's
  counts and their read time, so a failed lookup neither clears nor raises
  PeerOwnerUnrecorded. Shipped promtool case 2 asserted unrecorded 0 on an
  unread cycle; it now asserts the page stays up on the carried count.
- The loader enforces the schema and never raises: a malformed file is not
  loaded; an entry with a missing field, a bad date or an unknown key is
  refused; a repeated peer id refuses both. New metrics say whether the file
  was configured and loaded and how many entries were refused.
- Rules keep the instance label (two writers page once each, with their own
  count) and add PeerOwnerMetricsAbsent, PeerOwnerPartlyUnread and
  PeerOwnerExceptionsNotLoaded.
- The deploy validates the overlay's file before it lands, removes a host
  file the overlay no longer has, and the seed run gets the timer's
  environment.
- peer_gone and partly unread names are logged.

Each item has a test that fails on the previous head; the new CLI test runs
the real program against a fake NetBird store and a fake portal.

Signed-off-by: dlf-dds <dene.farrell.gov@gmail.com>


def env():
e = jinja2.Environment()
return hits[0]

def test_the_probe_asks_the_operator_route_the_writer_uses(self):
self.assertNotIn("assert-portal-key-accepted", open(TASKS).read(),
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