feat: config mode vs api mode for topology management

[micpapal]

Description

Summary

Implements dual topology management modes for the SLIM control plane: config-managed (YAML file is source of truth) and API-managed (DB is source of truth with full CRUD via gRPC/CLI). Adds topology mutation commands, persistence for config→API mode transitions, and controller restart resilience.

Topology management modes

The control plane operates in one of two mutually exclusive modes based on whether the config file contains a topology section:

Config mode (topology section present)

• Config file is the single source of truth
• On restart: all state (runtime + topology) is wiped and config is re-applied
• Dynamic $group expansion re-evaluated when new nodes register
• Mutation APIs return an error: "topology is config-managed"
• Topology is persisted to DB after expansion (for seamless transition to API mode)

API mode (no topology section)

• DB is the single source of truth
• On restart: runtime state (nodes, links, routes) is cleared but topology config (segments, segment links) is preserved from DB
• Full CRUD operations available via slimctl and gRPC APIs
• Nodes re-register and links/routes are rebuilt automatically

Changes

Topology persistence and startup logic

• clear_runtime_state() — new DB method that clears nodes, links, routes but preserves topology config. Called on API-mode startup.
• clear_all_state() — clears everything (runtime + topology). Called on config-mode startup. Internally delegates to clear_runtime_state().
• persist_segments_to_db() — in config mode, writes expanded segments/links to DB after rebuild_link_graph(), enabling config→API mode transition without losing topology
• load_topology_from_db() — on API-mode startup, reconstructs in-memory segment graphs from DB

Topology mutation APIs (API mode only)

• controller segment add <NAME> — create a new segment
• controller segment remove <NAME> — remove a segment and all its links
• controller link add --segment <S> <GROUP_A> <GROUP_B> — add inter-group link to a segment
• controller link remove --segment <S> <GROUP_A> <GROUP_B> — remove inter-group link from a segment
• Corresponding gRPC RPCs: AddSegment, RemoveSegment, AddTopologyLink, RemoveTopologyLink
• Guards prevent mutation in config-managed mode

Node reconnection resilience

• On controller restart, nodes reconnect and rebuild their links/routes automatically
• Stale nodes (that don't reconnect) are no longer persisted across restarts — cleared by clear_runtime_state()
• Node disconnect logic properly cleans up routes and reassigns gateway links

DB schema additions

• topology_segments table — stores segment definitions
• topology_segment_links table — stores inter-group links within each segment
• SQLite add_link_to_segment made idempotent (duplicate links ignored)
• Links allowed for groups that don't have registered nodes yet

Related

• Closes Config mode vs API mode for topology management #1768

Type of Change

• Bugfix
• New Feature
• Breaking Change
• Refactor
• Documentation
• Other (please describe)

Checklist

• I have read the contributing guidelines
• Existing issues have been referenced (where applicable)
• I have verified this change is not present in other open pull requests
• Functionality is documented
• All code style checks pass
• New code contribution is covered by automated tests
• All new and existing tests pass

[github-actions]

The latest Buf updates on your PR. Results from workflow ci-buf / buf (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	✅ passed	✅ passed	⏩ skipped	Jun 30, 2026, 12:25 PM

[codecov]

Codecov Report

❌ Patch coverage is 78.74225% with 240 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
crates/slimctl/src/commands/controller.rs	0.00%	106 Missing ⚠️
crates/control-plane/src/db/sqlite/mod.rs	64.10%	42 Missing ⚠️
crates/controller/src/service.rs	40.38%	31 Missing ⚠️
crates/control-plane/src/route_service.rs	94.35%	21 Missing ⚠️
crates/control-plane/src/services/northbound.rs	38.46%	16 Missing ⚠️
crates/proto/src/gen/controlplane.proto.v1.rs	94.69%	12 Missing ⚠️
crates/control-plane/src/route_service/routes.rs	82.05%	7 Missing ⚠️
crates/control-plane/src/config.rs	93.10%	4 Missing ⚠️
crates/control-plane/src/server.rs	95.23%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!