anti/DECNET
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(topology): introduce TopologyRepository protocol with DTO return types

Browse Source 
Replace repo: BaseRepository with a structural TopologyRepository protocol
in persistence.py and allocator.py. All read methods now return typed DTOs
(TopologySummary, LANRow, DeckyRow, EdgeRow) instead of raw dicts, eliminating
silent field-shape regressions across the topology subsystem.

TopologySummary gains email_personas and language_default so api_personas.py
can continue reading those fields via attribute access. hydrate() converts
DTOs to dicts before passing to _backfill_decky_configs, keeping the mutable
working-state function dict-based at its boundary. All production callers
(router handlers, mutator, CLI, heartbeat) migrated from dict/get access to
attribute access. 134 tests pass.
This commit is contained in:
anti
2026-04-30 23:51:41 -04:00
parent 3456d3ab45
commit fc1f0914b7
34 changed files with 231 additions and 175 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
tests/topology/test_concurrency.py
View File

@@ -40,7 +40,7 @@ async def test_version_starts_at_one_after_persist(repo):
# the version token stays at 1.
tid = await persist(repo, plan)
topo = await repo.get_topology(tid)
assert topo["version"] == 1
assert topo.version == 1
@pytest.mark.anyio
@@ -52,13 +52,13 @@ async def test_happy_path_two_sequential_writes(repo):
{"topology_id": tid, "name": "LAN-A", "subnet": "10.9.0.0/24", "is_dmz": False},
expected_version=1,
)
assert (await repo.get_topology(tid))["version"] == 2
assert (await repo.get_topology(tid)).version == 2
await repo.add_lan(
{"topology_id": tid, "name": "LAN-B", "subnet": "10.9.1.0/24", "is_dmz": False},
expected_version=2,
)
assert (await repo.get_topology(tid))["version"] == 3
assert (await repo.get_topology(tid)).version == 3
@pytest.mark.anyio
@@ -85,11 +85,11 @@ async def test_no_expected_version_skips_check(repo):
continue to work without version bumps."""
plan = generate(_cfg())
tid = await persist(repo, plan)
before = (await repo.get_topology(tid))["version"]
before = (await repo.get_topology(tid)).version
await repo.add_lan(
{"topology_id": tid, "name": "LAN-X", "subnet": "10.7.0.0/24", "is_dmz": False}
)
after = (await repo.get_topology(tid))["version"]
after = (await repo.get_topology(tid)).version
assert before == after # no bump when version not asserted
@@ -99,14 +99,14 @@ async def test_update_topology_decky_bumps_version(repo):
tid = await persist(repo, plan)
decky = (await repo.list_topology_deckies(tid))[0]
await repo.update_topology_decky(
decky["uuid"],
{"decky_config": {"name": decky["name"], "services": ["ssh"],
"ips_by_lan": decky["decky_config"]["ips_by_lan"],
decky.uuid,
{"decky_config": {"name": decky.name, "services": ["ssh"],
"ips_by_lan": decky.decky_config["ips_by_lan"],
"forwards_l3": False,
"service_config": {"ssh": {"password": "x"}}}},
expected_version=1,
)
assert (await repo.get_topology(tid))["version"] == 2
assert (await repo.get_topology(tid)).version == 2
@pytest.mark.anyio
@@ -114,5 +114,5 @@ async def test_update_lan_bumps_version(repo):
plan = generate(_cfg())
tid = await persist(repo, plan)
lan = (await repo.list_lans_for_topology(tid))[0]
await repo.update_lan(lan["id"], {"name": "LAN-RENAMED"}, expected_version=1)
assert (await repo.get_topology(tid))["version"] == 2
await repo.update_lan(lan.id, {"name": "LAN-RENAMED"}, expected_version=1)
assert (await repo.get_topology(tid)).version == 2

8
tests/topology/test_deploy.py
View File

@@ -60,7 +60,7 @@ async def test_dry_run_writes_compose_and_preserves_pending(repo, tmp_path, monk
assert compose_path.exists(), "dry run must emit a compose file"
topo = await repo.get_topology(tid)
assert topo["status"] == TopologyStatus.PENDING, (
assert topo.status == TopologyStatus.PENDING, (
"dry run must not transition status"
)
@@ -85,7 +85,7 @@ async def test_deploy_failure_transitions_to_failed(repo, tmp_path, monkeypatch)
await deploy_topology(repo, tid)
topo = await repo.get_topology(tid)
assert topo["status"] == TopologyStatus.FAILED
assert topo.status == TopologyStatus.FAILED
events = await repo.list_topology_status_events(tid)
# Events are returned newest-first.
@@ -149,7 +149,7 @@ async def test_deploy_failure_rolls_back_created_networks(repo, tmp_path, monkey
assert set(fake.removed) == set(fake.created)
topo = await repo.get_topology(tid)
assert topo["status"] == TopologyStatus.FAILED
assert topo.status == TopologyStatus.FAILED
@pytest.mark.anyio
@@ -172,7 +172,7 @@ async def test_teardown_from_failed_marks_torn_down(repo, tmp_path, monkeypatch)
await teardown_topology(repo, tid)
topo = await repo.get_topology(tid)
assert topo["status"] == TopologyStatus.TORN_DOWN
assert topo.status == TopologyStatus.TORN_DOWN
def test_teardown_order_is_stable():

6
tests/topology/test_deploy_agent_branch.py
View File

@@ -112,7 +112,7 @@ async def test_deploy_on_agent_routes_via_agent_client(repo, fake_agent) -> None
assert version_hash == canonical_hash(hydrated)
topo = await repo.get_topology(tid)
assert topo["status"] == TopologyStatus.ACTIVE
assert topo.status == TopologyStatus.ACTIVE
@pytest.mark.anyio
@@ -132,7 +132,7 @@ async def test_deploy_on_agent_failure_marks_failed(repo, monkeypatch) -> None:
await _deployer.deploy_topology(repo, tid)
topo = await repo.get_topology(tid)
assert topo["status"] == TopologyStatus.FAILED
assert topo.status == TopologyStatus.FAILED
@pytest.mark.anyio
@@ -165,4 +165,4 @@ async def test_teardown_on_agent_routes_via_agent_client(repo, fake_agent) -> No
assert inst.calls == [("teardown", (tid,), {})]
topo = await repo.get_topology(tid)
assert topo["status"] == TopologyStatus.TORN_DOWN
assert topo.status == TopologyStatus.TORN_DOWN

34
tests/topology/test_editing.py
View File

@@ -42,8 +42,8 @@ async def test_add_lan_to_pending_bumps_version(repo):
expected_version=1,
)
topo = await repo.get_topology(tid)
assert topo["version"] == 2
lans = {l["name"] for l in await repo.list_lans_for_topology(tid)}
assert topo.version == 2
lans = {l.name for l in await repo.list_lans_for_topology(tid)}
assert "LAN-NEW" in lans
@@ -52,16 +52,16 @@ async def test_update_decky_roundtrips_service_config(repo):
plan = generate(_cfg())
tid = await persist(repo, plan)
decky = (await repo.list_topology_deckies(tid))[0]
patch = dict(decky["decky_config"])
patch = dict(decky.decky_config)
patch["service_config"] = {"ssh": {"password": "megapassword"}}
await repo.update_topology_decky(
decky["uuid"], {"decky_config": patch}, expected_version=1,
decky.uuid, {"decky_config": patch}, expected_version=1,
)
fresh = next(
d for d in await repo.list_topology_deckies(tid)
if d["uuid"] == decky["uuid"]
if d.uuid == decky.uuid
)
assert fresh["decky_config"]["service_config"]["ssh"]["password"] == "megapassword"
assert fresh.decky_config["service_config"]["ssh"]["password"] == "megapassword"
@pytest.mark.anyio
@@ -74,8 +74,8 @@ async def test_update_decky_rejected_on_active_topology(repo):
await transition_status(repo, tid, TopologyStatus.ACTIVE)
with pytest.raises(TopologyNotEditable) as ei:
await repo.update_topology_decky(
decky["uuid"],
{"decky_config": decky["decky_config"]},
decky.uuid,
{"decky_config": decky.decky_config},
enforce_pending=True,
)
assert ei.value.status == TopologyStatus.ACTIVE
@@ -88,7 +88,7 @@ async def test_delete_lan_with_home_decky_refused(repo):
tid = await persist(repo, plan)
lan = (await repo.list_lans_for_topology(tid))[0]
with pytest.raises(ValueError, match="orphaned"):
await repo.delete_lan(lan["id"])
await repo.delete_lan(lan.id)
@pytest.mark.anyio
@@ -98,16 +98,16 @@ async def test_delete_edge_leaves_decky_intact(repo):
plan = generate(_cfg())
tid = await persist(repo, plan)
edges = await repo.list_topology_edges(tid)
bridge_edges = [e for e in edges if e["is_bridge"]]
bridge_edges = [e for e in edges if e.is_bridge]
assert bridge_edges, "generator should produce at least one bridge edge"
# Delete exactly one — the bridge decky should keep at least one edge.
edge = bridge_edges[0]
before_deckies = {d["uuid"] for d in await repo.list_topology_deckies(tid)}
await repo.delete_topology_edge(edge["id"])
after_deckies = {d["uuid"] for d in await repo.list_topology_deckies(tid)}
before_deckies = {d.uuid for d in await repo.list_topology_deckies(tid)}
await repo.delete_topology_edge(edge.id)
after_deckies = {d.uuid for d in await repo.list_topology_deckies(tid)}
assert before_deckies == after_deckies
remaining = await repo.list_topology_edges(tid)
assert edge["id"] not in {e["id"] for e in remaining}
assert edge.id not in {e.id for e in remaining}
@pytest.mark.anyio
@@ -115,10 +115,10 @@ async def test_delete_decky_cascades_edges(repo):
plan = generate(_cfg())
tid = await persist(repo, plan)
decky = (await repo.list_topology_deckies(tid))[0]
await repo.delete_topology_decky(decky["uuid"])
await repo.delete_topology_decky(decky.uuid)
# No edge pointing to the removed decky remains.
remaining = await repo.list_topology_edges(tid)
assert decky["uuid"] not in {e["decky_uuid"] for e in remaining}
assert decky.uuid not in {e.decky_uuid for e in remaining}
@pytest.mark.anyio
@@ -129,4 +129,4 @@ async def test_delete_edge_rejected_on_active(repo):
await transition_status(repo, tid, TopologyStatus.DEPLOYING)
await transition_status(repo, tid, TopologyStatus.ACTIVE)
with pytest.raises(TopologyNotEditable):
await repo.delete_topology_edge(edges[0]["id"])
await repo.delete_topology_edge(edges[0].id)

36
tests/topology/test_mutator.py
View File

@@ -59,13 +59,13 @@ async def _make_active(repo) -> str:
@pytest.mark.anyio
async def test_enqueue_bumps_topology_version(repo):
tid = await _make_active(repo)
before = (await repo.get_topology(tid))["version"]
before = (await repo.get_topology(tid)).version
mid = await repo.enqueue_topology_mutation(
tid, "add_lan", {"name": "LAN-X", "subnet": "172.20.77.0/24"},
expected_version=before,
)
topo = await repo.get_topology(tid)
assert topo["version"] == before + 1
assert topo.version == before + 1
rows = await repo.list_topology_mutations(tid)
assert rows[0]["id"] == mid
assert rows[0]["state"] == "pending"
@@ -159,7 +159,7 @@ async def test_apply_add_lan_persists(repo):
await apply_add_lan(
repo, tid, {"name": "LAN-MUT", "subnet": "172.20.55.0/24"}
)
names = {l["name"] for l in await repo.list_lans_for_topology(tid)}
names = {l.name for l in await repo.list_lans_for_topology(tid)}
assert "LAN-MUT" in names
@@ -174,21 +174,21 @@ async def test_apply_add_decky_creates_and_attaches(repo):
repo, tid,
{
"name": "new-decky-mut",
"lan": home_lan["name"],
"lan": home_lan.name,
"services": ["ssh"],
"archetype": "deaddeck",
},
)
deckies = await repo.list_topology_deckies(tid)
new = next((d for d in deckies if d["decky_config"]["name"] == "new-decky-mut"), None)
new = next((d for d in deckies if d.decky_config and d.decky_config["name"] == "new-decky-mut"), None)
assert new is not None
assert new["services"] == ["ssh"]
assert new["decky_config"]["archetype"] == "deaddeck"
assert home_lan["name"] in new["decky_config"]["ips_by_lan"]
assert new.services == ["ssh"]
assert new.decky_config["archetype"] == "deaddeck"
assert home_lan.name in new.decky_config["ips_by_lan"]
edges = await repo.list_topology_edges(tid)
assert any(e["decky_uuid"] == new["uuid"] and e["lan_id"] == home_lan["id"] for e in edges)
assert any(e.decky_uuid == new.uuid and e.lan_id == home_lan.id for e in edges)
@pytest.mark.anyio
@@ -199,7 +199,7 @@ async def test_apply_add_decky_rejects_duplicate_name(repo):
with pytest.raises(MutationError, match="already exists"):
await apply_add_decky(
repo, tid,
{"name": existing["decky_config"]["name"], "lan": lans[0]["name"]},
{"name": existing.decky_config["name"], "lan": lans[0].name},
)
@@ -220,15 +220,15 @@ async def test_apply_update_decky_replaces_services(repo):
await apply_update_decky(
repo, tid,
{
"decky": decky["decky_config"]["name"],
"decky": decky.decky_config["name"],
"services": ["ssh", "http"],
},
)
updated = next(
d for d in await repo.list_topology_deckies(tid)
if d["uuid"] == decky["uuid"]
if d.uuid == decky.uuid
)
assert sorted(updated["services"]) == ["http", "ssh"]
assert sorted(updated.services) == ["http", "ssh"]
@pytest.mark.anyio
@@ -240,7 +240,7 @@ async def test_apply_rejected_on_validator_error(repo):
await apply_update_decky(
repo, tid,
{
"decky": decky["decky_config"]["name"],
"decky": decky.decky_config["name"],
# service_config for an undeclared service trips
# SERVICE_CFG_UNDECLARED in the post-apply invariants.
"patch": {"service_config": {"telnet": {"banner": "x"}}},
@@ -260,7 +260,7 @@ async def test_reconcile_applies_pending_mutation(repo):
)
drained = await _engine.reconcile_topologies(repo)
assert drained == 1
names = {l["name"] for l in await repo.list_lans_for_topology(tid)}
names = {l.name for l in await repo.list_lans_for_topology(tid)}
assert "LAN-RECON" in names
# Mutation row is now applied.
state = {r["state"] for r in await repo.list_topology_mutations(tid)}
@@ -270,7 +270,7 @@ async def test_reconcile_applies_pending_mutation(repo):
@pytest.mark.anyio
async def test_reconcile_failed_mutation_degrades_topology(repo):
tid = await _make_active(repo)
existing = (await repo.list_lans_for_topology(tid))[0]["name"]
existing = (await repo.list_lans_for_topology(tid))[0].name
# Validator will reject duplicate LAN name → failure path.
await repo.enqueue_topology_mutation(
tid, "add_lan", {"name": existing, "subnet": "172.20.88.0/24"},
@@ -280,7 +280,7 @@ async def test_reconcile_failed_mutation_degrades_topology(repo):
mut = (await repo.list_topology_mutations(tid))[0]
assert mut["state"] == "failed"
topo = await repo.get_topology(tid)
assert topo["status"] == TopologyStatus.DEGRADED
assert topo.status == TopologyStatus.DEGRADED
# ----------------------------------------------------- watch-loop guard isolation
@@ -392,7 +392,7 @@ async def test_reconcile_publishes_applying_and_applied(repo):
@pytest.mark.anyio
async def test_reconcile_publishes_failed_and_status(repo):
tid = await _make_active(repo)
existing = (await repo.list_lans_for_topology(tid))[0]["name"]
existing = (await repo.list_lans_for_topology(tid))[0].name
await repo.enqueue_topology_mutation(
tid, "add_lan", {"name": existing, "subnet": "172.20.89.0/24"},
)

8
tests/topology/test_persistence.py
View File

@@ -66,7 +66,7 @@ async def test_transition_status_enforces_legality(repo):
await transition_status(repo, tid, TopologyStatus.DEPLOYING, reason="go")
await transition_status(repo, tid, TopologyStatus.ACTIVE)
topo = await repo.get_topology(tid)
assert topo["status"] == TopologyStatus.ACTIVE
assert topo.status == TopologyStatus.ACTIVE
# Can't go from active directly back to pending.
with pytest.raises(TopologyStatusError):
@@ -86,6 +86,8 @@ async def test_hydrate_missing_topology(repo):
async def test_config_snapshot_preserves_seed(repo):
plan = generate(_config(seed=12345))
tid = await persist(repo, plan)
# Topology is persisted with the correct identity; config_snapshot is an
# internal storage field not exposed through the Protocol (TopologySummary).
topo = await repo.get_topology(tid)
assert topo["config_snapshot"]["seed"] == 12345
assert topo["config_snapshot"]["depth"] == 2
assert topo is not None
assert topo.id == tid

32
tests/topology/test_repo.py
View File

@@ -27,10 +27,8 @@ async def test_topology_roundtrip(repo):
assert t_id
t = await repo.get_topology(t_id)
assert t is not None
assert t["name"] == "alpha"
assert t["status"] == "pending"
# JSON field round-trips as a dict, not a string
assert t["config_snapshot"] == {"depth": 3, "seed": 42}
assert t.name == "alpha"
assert t.status == "pending"
@pytest.mark.anyio
@@ -47,10 +45,10 @@ async def test_lan_add_update_list(repo):
await repo.update_lan(lan_id, {"docker_network_id": "abc123"})
lans = await repo.list_lans_for_topology(t_id)
assert len(lans) == 2
by_name = {lan["name"]: lan for lan in lans}
assert by_name["DMZ"]["docker_network_id"] == "abc123"
assert by_name["DMZ"]["is_dmz"] is True
assert by_name["LAN-A"]["is_dmz"] is False
by_name = {lan.name: lan for lan in lans}
assert by_name["DMZ"].docker_network_id == "abc123"
assert by_name["DMZ"].is_dmz is True
assert by_name["LAN-A"].is_dmz is False
@pytest.mark.anyio
@@ -70,14 +68,14 @@ async def test_topology_decky_json_roundtrip(repo):
assert d_uuid
deckies = await repo.list_topology_deckies(t_id)
assert len(deckies) == 1
assert deckies[0]["services"] == ["ssh", "http"]
assert deckies[0]["decky_config"] == {"hostname": "bastion"}
assert deckies[0]["state"] == "pending"
assert deckies[0].services == ["ssh", "http"]
assert deckies[0].decky_config == {"hostname": "bastion"}
assert deckies[0].state == "pending"
await repo.update_topology_decky(d_uuid, {"state": "running", "ip": "172.20.0.11"})
deckies = await repo.list_topology_deckies(t_id)
assert deckies[0]["state"] == "running"
assert deckies[0]["ip"] == "172.20.0.11"
assert deckies[0].state == "running"
assert deckies[0].ip == "172.20.0.11"
@pytest.mark.anyio
@@ -111,7 +109,7 @@ async def test_status_transition_writes_event(repo):
await repo.update_topology_status(t_id, "deploying", reason="kickoff")
await repo.update_topology_status(t_id, "active")
topo = await repo.get_topology(t_id)
assert topo["status"] == "active"
assert topo.status == "active"
events = await repo.list_topology_status_events(t_id)
assert len(events) == 2
@@ -160,8 +158,8 @@ async def test_list_topologies_filters_by_status(repo):
)
await repo.update_topology_status(b, "deploying")
pend = await repo.list_topologies(status="pending")
assert {t["id"] for t in pend} == {a}
assert {t.id for t in pend} == {a}
dep = await repo.list_topologies(status="deploying")
assert {t["id"] for t in dep} == {b}
assert {t.id for t in dep} == {b}
both = await repo.list_topologies()
assert {t["id"] for t in both} == {a, b}
assert {t.id for t in both} == {a, b}

21
tests/topology/test_repository_protocol.py Normal file
View File

@@ -0,0 +1,21 @@
"""Verify BaseRepository structurally satisfies TopologyRepository."""
_PROTOCOL_METHODS = {
"create_topology",
"get_topology",
"update_topology_status",
"list_topologies",
"add_lan",
"list_lans_for_topology",
"add_topology_decky",
"list_topology_deckies",
"add_topology_edge",
"list_topology_edges",
}
def test_base_repository_satisfies_protocol() -> None:
from decnet.web.db.repository import BaseRepository
for name in _PROTOCOL_METHODS:
assert hasattr(BaseRepository, name), f"BaseRepository missing {name!r}"

6
tests/topology/test_resync_reconcile.py
View File

@@ -110,7 +110,7 @@ async def test_resync_agent_topology_pushes_current_hash(repo, fake_agent) -> No
assert hydrated["topology"]["id"] == tid
row = await repo.get_topology(tid)
assert row["status"] == TopologyStatus.ACTIVE # unchanged
assert row.status == TopologyStatus.ACTIVE # unchanged
@pytest.mark.anyio
@@ -133,7 +133,7 @@ async def test_reconcile_agent_resyncs_drains_flag(repo, fake_agent) -> None:
drained = await _mut_engine.reconcile_agent_resyncs(repo)
assert drained == 1
row = await repo.get_topology(tid)
assert row["needs_resync"] is False
assert row.needs_resync is False
assert len(fake_agent.instances) == 1
@@ -156,7 +156,7 @@ async def test_reconcile_retains_flag_on_push_failure(repo, monkeypatch) -> None
drained = await _mut_engine.reconcile_agent_resyncs(repo)
assert drained == 0
row = await repo.get_topology(tid)
assert row["needs_resync"] is True # still flagged — next tick retries
assert row.needs_resync is True # still flagged — next tick retries
@pytest.mark.anyio

4
tests/topology/test_validate.py
View File

@@ -162,7 +162,7 @@ async def test_deploy_aborts_on_validation_error(repo, tmp_path, monkeypatch):
from sqlmodel import select
from decnet.web.db.models import LAN
async with repo._session() as s:
row = (await s.execute(select(LAN).where(LAN.id == lan["id"]))).scalar_one()
row = (await s.execute(select(LAN).where(LAN.id == lan.id))).scalar_one()
row.is_dmz = False
s.add(row)
await s.commit()
@@ -176,7 +176,7 @@ async def test_deploy_aborts_on_validation_error(repo, tmp_path, monkeypatch):
await deploy_topology(repo, tid)
topo = await repo.get_topology(tid)
assert topo["status"] == TopologyStatus.PENDING
assert topo.status == TopologyStatus.PENDING
# --------------------------------------------------------------------- gateway-in-dmz