Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
TypeScript diagramhomelabhomelab-infrastructure-observabilitynetworkproxmox-veself-hostedzigbeezwavezwave-js
"""The update-from-device endpoints (#484).
Three-way merge on the wire: a preview that changes nothing, an apply that only
saves a fully reviewed merge, and a staleness guard that refuses to run a
resolution made against a document that moved on.
"""
from httpx import AsyncClient
async def _device(client: AsyncClient, headers: dict, **body) -> dict:
payload = {"label": "nas-01", "hostname": "nas-01.lan", "ip": "192.168.1.20", "discovery_source": "manual", **body}
res = await client.post("/api/v1/scan/pending", json=payload, headers=headers)
assert res.status_code in (200, 201), res.text
return res.json()
async def _doc(client: AsyncClient, headers: dict, device: dict) -> dict:
res = await client.post(
"/api/v1/documents", json={"title": "nas", "kind": "device", "device_id": device["id"]}, headers=headers
)
assert res.status_code == 201, res.text
return res.json()
async def _set_ip(client: AsyncClient, headers: dict, device: dict, ip: str) -> None:
res = await client.patch(f"/api/v1/scan/pending/{device['id']}", json={"ip": ip}, headers=headers)
assert res.status_code == 200, res.text
async def _edit_ip(client: AsyncClient, headers: dict, doc: dict, ip: str) -> dict:
body = doc["body"].replace("| IP | 192.168.1.20 |", f"| IP | {ip} |")
res = await client.patch(f"/api/v1/documents/{doc['id']}", json={"body": body}, headers=headers)
assert res.status_code == 200, res.text
return res.json()
async def _preview(client: AsyncClient, headers: dict, doc_id: str, **kwargs) -> dict:
res = await client.post(f"/api/v1/documents/{doc_id}/update-preview", json=kwargs, headers=headers)
assert res.status_code == 200, res.text
return res.json()
# ── auth and guards ─────────────────────────────────────────────────────────
async def test_preview_requires_auth(client: AsyncClient):
assert (await client.post("/api/v1/documents/x/update-preview", json={})).status_code == 401
async def test_apply_requires_auth(client: AsyncClient):
assert (await client.post("/api/v1/documents/x/update-from-device", json={})).status_code == 401
async def test_preview_of_an_unknown_document_is_404(client: AsyncClient, headers: dict):
res = await client.post("/api/v1/documents/x/update-preview", json={}, headers=headers)
assert res.status_code == 404
async def test_apply_of_an_unknown_document_is_404(client: AsyncClient, headers: dict):
res = await client.post("/api/v1/documents/x/update-from-device", json={"preview_id": "x"}, headers=headers)
assert res.status_code == 404
async def test_preview_of_a_plain_page_is_rejected(client: AsyncClient, headers: dict):
res = await client.post("/api/v1/documents", json={"title": "Notes"}, headers=headers)
doc = res.json()
res = await client.post(f"/api/v1/documents/{doc['id']}/update-preview", json={}, headers=headers)
assert res.status_code == 400
async def test_apply_of_a_plain_page_is_rejected(client: AsyncClient, headers: dict):
res = await client.post("/api/v1/documents", json={"title": "Notes"}, headers=headers)
doc = res.json()
res = await client.post(
f"/api/v1/documents/{doc['id']}/update-from-device", json={"preview_id": "x"}, headers=headers
)
assert res.status_code == 400
# ── preview ─────────────────────────────────────────────────────────────────
async def test_a_stable_device_previews_no_changes(client: AsyncClient, headers: dict):
device = await _device(client, headers)
doc = await _doc(client, headers, device)
preview = await _preview(client, headers, doc["id"])
assert preview["unresolved"] == []
assert all(c["status"] in ("same", "auto") for c in preview["changes"])
# An untouched document: the merge is the document.
assert preview["proposed_body"] == doc["body"]
async def test_an_untouched_field_is_offered_for_automatic_application(client: AsyncClient, headers: dict):
device = await _device(client, headers)
doc = await _doc(client, headers, device)
await _set_ip(client, headers, device, "192.168.1.99")
preview = await _preview(client, headers, doc["id"])
ip = next(c for c in preview["changes"] if c["id"] == "device-info.IP")
assert ip["status"] == "auto"
assert ip["device"] == "192.168.1.99"
assert preview["unresolved"] == []
assert "| IP | 192.168.1.99 |" in preview["proposed_body"]
async def test_a_user_edit_against_a_device_change_is_a_conflict(client: AsyncClient, headers: dict):
device = await _device(client, headers)
doc = await _doc(client, headers, device)
await _edit_ip(client, headers, doc, "192.168.1.20 (jump host)")
await _set_ip(client, headers, device, "192.168.1.99")
preview = await _preview(client, headers, doc["id"])
ip = next(c for c in preview["changes"] if c["id"] == "device-info.IP")
assert ip["status"] == "conflict"
assert ip["documented"] == "192.168.1.20 (jump host)"
assert ip["device"] == "192.168.1.99"
assert preview["unresolved"] == ["device-info.IP"]
# An unresolved merge keeps the user's text — the preview is a draft.
assert "192.168.1.20 (jump host)" in preview["proposed_body"]
async def test_a_preview_folds_resolutions_in(client: AsyncClient, headers: dict):
device = await _device(client, headers)
doc = await _doc(client, headers, device)
await _edit_ip(client, headers, doc, "192.168.1.20 (jump host)")
await _set_ip(client, headers, device, "192.168.1.99")
preview = await _preview(
client, headers, doc["id"],
resolutions=[{"id": "device-info.IP", "choice": "custom", "custom": "10.9.8.7 (lan) "}],
)
ip = next(c for c in preview["changes"] if c["id"] == "device-info.IP")
assert ip["resolution"] == "custom"
assert preview["unresolved"] == []
assert "| IP | 10.9.8.7 (lan) |" in preview["proposed_body"]
# ── apply ───────────────────────────────────────────────────────────────────
async def test_apply_lands_an_automatic_merge(client: AsyncClient, headers: dict):
device = await _device(client, headers)
doc = await _doc(client, headers, device)
await _set_ip(client, headers, device, "192.168.1.99")
preview_id = (await _preview(client, headers, doc["id"]))["preview_id"]
res = await client.post(
f"/api/v1/documents/{doc['id']}/update-from-device",
json={"preview_id": preview_id, "resolutions": []},
headers=headers,
)
assert res.status_code == 200, res.text
updated = res.json()
assert "| IP | 192.168.1.99 |" in updated["body"]
# The device is recorded as documented again — the drift banner clears.
assert updated["facts_snapshot"]["ip"] == "192.168.1.99"
assert updated["drifted"] is False
assert (await client.get(f"/api/v1/documents/{doc['id']}", headers=headers)).json()["drifted"] is False
# The old body is in history, flagged as a sync.
revisions = (await client.get(f"/api/v1/documents/{doc['id']}/revisions", headers=headers)).json()
assert [r["reason"] for r in revisions] == ["sync"]
async def test_a_body_that_already_matches_the_device_is_not_drifted(client: AsyncClient, headers: dict):
"""The user already wrote the device's new value: an update would have
nothing to offer, so neither the document, the list nor coverage flag it."""
device = await _device(client, headers)
doc = await _doc(client, headers, device)
await _set_ip(client, headers, device, "192.168.1.99")
assert (await client.get(f"/api/v1/documents/{doc['id']}", headers=headers)).json()["drifted"] is True
await _edit_ip(client, headers, doc, "192.168.1.99")
assert (await client.get(f"/api/v1/documents/{doc['id']}", headers=headers)).json()["drifted"] is False
listed = (await client.get("/api/v1/documents", headers=headers)).json()
assert next(d for d in listed if d["id"] == doc["id"])["drifted"] is False
assert (await client.get("/api/v1/documents/coverage", headers=headers)).json()["drifted"] == 0
async def test_the_list_flags_each_drifted_document_on_its_own_device(client: AsyncClient, headers: dict):
"""The list resolves every candidate's render context in one batch; each
document must still be judged against its own device."""
docs = {}
for name, ip in (("nas-a", "192.168.1.31"), ("nas-b", "192.168.1.32"), ("nas-c", "192.168.1.33")):
device = await _device(client, headers, label=name, hostname=f"{name}.lan", ip=ip)
docs[name] = (device, await _doc(client, headers, device))
for name, ip in (("nas-a", "192.168.1.41"), ("nas-b", "192.168.1.42"), ("nas-c", "192.168.1.43")):
await _set_ip(client, headers, docs[name][0], ip)
# nas-c's owner already wrote the new address down.
matching = docs["nas-c"][1]
res = await client.patch(
f"/api/v1/documents/{matching['id']}",
json={"body": matching["body"].replace("| IP | 192.168.1.33 |", "| IP | 192.168.1.43 |")},
headers=headers,
)
assert res.status_code == 200, res.text
listed = {d["id"]: d["drifted"] for d in (await client.get("/api/v1/documents", headers=headers)).json()}
assert listed[docs["nas-a"][1]["id"]] is True
assert listed[docs["nas-b"][1]["id"]] is True
assert listed[matching["id"]] is False
assert (await client.get("/api/v1/documents/coverage", headers=headers)).json()["drifted"] == 2
async def test_a_conflict_keeps_the_document_drifted(client: AsyncClient, headers: dict):
"""The user and the device disagree: that is exactly what the flag is for."""
device = await _device(client, headers)
doc = await _doc(client, headers, device)
await _edit_ip(client, headers, doc, "nas.example.lan")
await _set_ip(client, headers, device, "192.168.1.99")
assert (await client.get(f"/api/v1/documents/{doc['id']}", headers=headers)).json()["drifted"] is True
async def test_apply_with_nothing_to_change_records_the_facts_without_a_revision(
client: AsyncClient, headers: dict
):
device = await _device(client, headers)
doc = await _doc(client, headers, device)
await _set_ip(client, headers, device, "192.168.1.99")
edited = await _edit_ip(client, headers, doc, "192.168.1.99")
preview = await _preview(client, headers, doc["id"])
assert preview["summary"] == []
assert preview["unresolved"] == []
res = await client.post(
f"/api/v1/documents/{doc['id']}/update-from-device",
json={"preview_id": preview["preview_id"], "resolutions": []},
headers=headers,
)
assert res.status_code == 200, res.text
updated = res.json()
assert updated["body"] == edited["body"]
assert updated["facts_snapshot"]["ip"] == "192.168.1.99"
assert updated["drifted"] is False
# Nothing was rewritten, so history gains no sync revision.
revisions = (await client.get(f"/api/v1/documents/{doc['id']}/revisions", headers=headers)).json()
assert "sync" not in [r["reason"] for r in revisions]
async def test_apply_records_a_durable_decision(client: AsyncClient, headers: dict):
device = await _device(client, headers)
doc = await _doc(client, headers, device)
await _edit_ip(client, headers, doc, "192.168.1.20 (primary)")
await _set_ip(client, headers, device, "192.168.1.99")
preview = await _preview(
client, headers, doc["id"],
resolutions=[{"id": "device-info.IP", "choice": "keep"}],
)
res = await client.post(
f"/api/v1/documents/{doc['id']}/update-from-device",
json={"preview_id": preview["preview_id"], "resolutions": [{"id": "device-info.IP", "choice": "keep"}]},
headers=headers,
)
assert res.status_code == 200, res.text
assert "| IP | 192.168.1.20 (primary) |" in res.json()["body"]
async def test_a_kept_value_is_surfaced_again_on_the_next_change(client: AsyncClient, headers: dict):
"""The baseline is the generated body, never the merged one, so a deliberate
keep is not permanent blindness — the next device move asks once more."""
device = await _device(client, headers)
doc = await _doc(client, headers, device)
await _edit_ip(client, headers, doc, "192.168.1.20 (primary)")
await _set_ip(client, headers, device, "192.168.1.99")
preview = await _preview(client, headers, doc["id"])
assert preview["unresolved"] == ["device-info.IP"]
# User keeps their note and applies.
preview = await _preview(client, headers, doc["id"], resolutions=[{"id": "device-info.IP", "choice": "keep"}])
res = await client.post(
f"/api/v1/documents/{doc['id']}/update-from-device",
json={"preview_id": preview["preview_id"], "resolutions": [{"id": "device-info.IP", "choice": "keep"}]},
headers=headers,
)
assert res.status_code == 200, res.text
assert "192.168.1.20 (primary)" in res.json()["body"]
# Device stays put: the kept value is quiet.
steady = await _preview(client, headers, doc["id"])
assert steady["unresolved"] == []
# The device moves again: the kept value is in question once more.
await _set_ip(client, headers, device, "192.168.1.120")
later = await _preview(client, headers, doc["id"])
assert later["unresolved"] == ["device-info.IP"]
async def test_kept_hostname_is_acknowledged_once_per_ip_change(client: AsyncClient, headers: dict):
"""Each Keep records the current IP as baseline without losing the hostname."""
device = await _device(
client,
headers,
label="homelabcluster",
hostname="homelabcluster.example.lan",
ip="192.168.10.10",
)
doc = await _doc(client, headers, device)
hostname = "homelabcluster.example.lan"
edited_body = doc["body"].replace("| IP | 192.168.10.10 |", f"| IP | {hostname} |")
edit = await client.patch(
f"/api/v1/documents/{doc['id']}", json={"body": edited_body}, headers=headers
)
assert edit.status_code == 200, edit.text
# The original baseline was .10, so the reviewed .20 needs an initial Keep.
await _set_ip(client, headers, device, "192.168.10.20")
first = await _preview(client, headers, doc["id"])
assert first["unresolved"] == ["device-info.IP"]
applied = await client.post(
f"/api/v1/documents/{doc['id']}/update-from-device",
json={"preview_id": first["preview_id"], "resolutions": [{"id": "device-info.IP", "choice": "keep"}]},
headers=headers,
)
assert applied.status_code == 200, applied.text
assert f"| IP | {hostname} |" in applied.json()["body"]
# The prior body is recoverable through the global revision URL, not a
# document-nested lookalike route.
revisions = (await client.get(f"/api/v1/documents/{doc['id']}/revisions", headers=headers)).json()
sync = next(revision for revision in revisions if revision["reason"] == "sync")
previous = await client.get(f"/api/v1/documents/revisions/{sync['id']}", headers=headers)
assert previous.status_code == 200, previous.text
assert previous.json()["body"] == edited_body
quiet = await _preview(client, headers, doc["id"])
assert quiet["unresolved"] == []
await _set_ip(client, headers, device, "192.168.10.25")
second = await _preview(client, headers, doc["id"])
assert second["unresolved"] == ["device-info.IP"]
applied = await client.post(
f"/api/v1/documents/{doc['id']}/update-from-device",
json={"preview_id": second["preview_id"], "resolutions": [{"id": "device-info.IP", "choice": "keep"}]},
headers=headers,
)
assert applied.status_code == 200, applied.text
assert applied.json()["facts_snapshot"]["ip"] == "192.168.10.25"
assert (await _preview(client, headers, doc["id"]))["unresolved"] == []
await _set_ip(client, headers, device, "192.168.10.30")
later = await _preview(client, headers, doc["id"])
assert later["unresolved"] == ["device-info.IP"]
async def test_apply_rejects_a_stale_preview(client: AsyncClient, headers: dict):
device = await _device(client, headers)
doc = await _doc(client, headers, device)
await _set_ip(client, headers, device, "192.168.1.99")
preview_id = (await _preview(client, headers, doc["id"]))["preview_id"]
# The document is edited while the preview is open.
res = await client.patch(
f"/api/v1/documents/{doc['id']}", json={"body": doc["body"] + "\n"}, headers=headers
)
assert res.status_code == 200, res.text
res = await client.post(
f"/api/v1/documents/{doc['id']}/update-from-device",
json={"preview_id": preview_id, "resolutions": []},
headers=headers,
)
assert res.status_code == 409
async def test_apply_rejects_unresolved_conflicts(client: AsyncClient, headers: dict):
device = await _device(client, headers)
doc = await _doc(client, headers, device)
await _edit_ip(client, headers, doc, "192.168.1.20 (jump host)")
await _set_ip(client, headers, device, "192.168.1.99")
preview_id = (await _preview(client, headers, doc["id"]))["preview_id"]
res = await client.post(
f"/api/v1/documents/{doc['id']}/update-from-device",
json={"preview_id": preview_id, "resolutions": []},
headers=headers,
)
assert res.status_code == 400
assert "IP address" in res.json()["detail"]
async def test_apply_rejects_a_device_change_made_while_the_preview_was_open(
client: AsyncClient, headers: dict
):
"""A device that moves on during review is a different review thread.
The preview id binds the live device facts and generated context the
proposal was computed from — not just the document state — so applying an
old resolution to a device that changed must fail with 409 and save
nothing: no body change and no history entry.
"""
device = await _device(client, headers)
doc = await _doc(client, headers, device)
doc = await _edit_ip(client, headers, doc, "nas.example.lan")
await _set_ip(client, headers, device, "192.168.1.30")
preview = await _preview(
client, headers, doc["id"], resolutions=[{"id": "device-info.IP", "choice": "device"}]
)
await _set_ip(client, headers, device, "192.168.1.40")
# The device moved on, so a fresh preview is a different id now.
fresh = await _preview(client, headers, doc["id"])
assert preview["preview_id"] != fresh["preview_id"]
res = await client.post(
f"/api/v1/documents/{doc['id']}/update-from-device",
json={
"preview_id": preview["preview_id"],
"resolutions": [{"id": "device-info.IP", "choice": "device"}],
},
headers=headers,
)
assert res.status_code == 409
# Nothing landed: the un-reviewed .40 is not in the body, the user edit
# survives, drift is untouched and no sync history was written.
current = (await client.get(f"/api/v1/documents/{doc['id']}", headers=headers)).json()
assert "| IP | 192.168.1.40 |" not in current["body"]
assert "| IP | nas.example.lan |" in current["body"]
assert current["drifted"] is True
# No sync history was written — the rejected apply recorded nothing, only
# the user's own earlier body edit exists.
revisions = (await client.get(f"/api/v1/documents/{doc['id']}/revisions", headers=headers)).json()
assert [r["reason"] for r in revisions] == ["edit"]
async def test_apply_rejects_a_generated_content_only_device_change(
client: AsyncClient, headers: dict
):
"""A device edit that only changes the *rendered* document binds too.
The device notes print into the generated body but are deliberately absent
from `facts_snapshot`, so changing them between preview and apply is a
rendered-content-only change: only a preview id that binds the generated
body itself can reject it.
"""
device = await _device(client, headers)
doc = await _doc(client, headers, device)
res = await client.patch(
f"/api/v1/scan/pending/{device['id']}", json={"notes": "serve the home media"}, headers=headers
)
assert res.status_code == 200, res.text
preview = await _preview(client, headers, doc["id"])
res = await client.patch(
f"/api/v1/scan/pending/{device['id']}",
json={"notes": "serve the home media — NFS too"},
headers=headers,
)
assert res.status_code == 200, res.text
# Same facts, same context — only the rendered body differs.
fresh = await _preview(client, headers, doc["id"])
assert preview["preview_id"] != fresh["preview_id"]
res = await client.post(
f"/api/v1/documents/{doc['id']}/update-from-device",
json={"preview_id": preview["preview_id"], "resolutions": []},
headers=headers,
)
assert res.status_code == 409
# Nothing landed: the body is untouched and no sync history was written.
assert (await client.get(f"/api/v1/documents/{doc['id']}", headers=headers)).json()["body"] == doc["body"]
revisions = (await client.get(f"/api/v1/documents/{doc['id']}/revisions", headers=headers)).json()
assert [r["reason"] for r in revisions] == []