feat: netlink

[marcinpsk]

Summary by CodeRabbit

• New Features

  • Added continuous network-topology monitoring through route netlink.
  • AgentX requests now use the latest published topology snapshot.
  • Added comprehensive real-network-namespace integration coverage.

• Configuration

  • Replaced refresh with reconcile, defaulting to a 3600-second interval.
  • Invalid or obsolete refresh settings are rejected.

• Bug Fixes

  • Improved handling of topology changes, acquisition failures, and lost update continuity.

• Documentation

  • Updated the README, man page, architecture documentation, and service guidance for netlink-based operation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 8a10fe35-0f2b-4bc1-ae85-f8c2b7df21e0

📥 Commits

Reviewing files that changed from the base of the PR and between f819fb9 and 5aa74ec.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (33)

• .github/real-namespace.Dockerfile
• .github/workflows/checks.yml
• .opengrep/README.md
• .opengrep/agentx-ifstack-rules.yaml
• .opengrep/tests/agentx-try-wait-outside-finish.rs
• CLAUDE.md
• Cargo.toml
• README.md
• docs/adr/0002-implement-the-netlink-monitor-as-a-process-actor.md
• packaging/agentx-ifstack.8
• packaging/agentx-ifstack.service
• packaging/agentx-ifstack.toml
• packaging/test_policy.py
• src/config.rs
• src/link.rs
• src/main.rs
• src/mib.rs
• src/monitor.rs
• src/netlink.rs
• src/session.rs
• tests/config_cli.rs
• tests/fixtures/bond.json
• tests/fixtures/bridge.json
• tests/fixtures/bridge_vlan_bond.json
• tests/fixtures/plain.json
• tests/fixtures/proxmox.json
• tests/fixtures/vlan.json
• tests/fixtures/vlan_on_bond.json
• tests/fixtures/vxlan.json
• tests/real_namespace.rs
• tests/session.rs
• tests/support/agentx.rs
• tests/support/mod.rs

💤 Files with no reviewable changes (11)

• packaging/agentx-ifstack.service
• tests/fixtures/vlan_on_bond.json
• tests/session.rs
• tests/fixtures/bridge_vlan_bond.json
• tests/fixtures/vlan.json
• tests/fixtures/vxlan.json
• tests/fixtures/plain.json
• .opengrep/tests/agentx-try-wait-outside-finish.rs
• tests/fixtures/bridge.json
• tests/fixtures/bond.json
• tests/fixtures/proxmox.json

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

Walkthrough

The daemon now monitors interface topology through typed route-netlink messages. A background monitor publishes MIB snapshots for AgentX sessions. The refresh setting and iproute runtime dependency are removed. New real-namespace tests and constrained CI execution validate the implementation.

Changes

Topology contracts and configuration

Layer / File(s)	Summary
Typed topology and MIB model src/link.rs, src/mib.rs, Cargo.toml	Typed link observations and direct stacking relationships replace JSON parsing. MIB rows are derived from topology data. Netlink crates are added.
Configuration contract src/config.rs, packaging/agentx-ifstack.toml, tests/config_cli.rs	refresh is replaced by reconcile, with a 3600-second default. The old key is rejected.
Architecture record docs/adr/0002-implement-the-netlink-monitor-as-a-process-actor.md	The monitor actor, netlink adapter, publication interface, scheduling, continuity handling, and verification seams are documented.

Route-netlink acquisition

Layer / File(s)	Summary
Netlink adapter src/netlink.rs	NetlinkSource subscribes to link notifications and performs bounded RTM_GETLINK inventories. It validates message sequences, completion, truncation, interruption, sender, payloads, and continuity failures.

Monitor scheduling and publication

Layer / File(s)	Summary
Monitor actor src/monitor.rs, src/main.rs	The monitor schedules inventories, applies retry and event backoff, tracks continuity generations, publishes MIB snapshots, and handles monitor termination.
AgentX snapshot reads src/session.rs	AgentX requests read the shared snapshot. Reads return ProcessingError when no snapshot is available. The ip subprocess runner and local cache are removed.

Real namespace validation and CI

Layer / File(s)	Summary
Integration suite tests/real_namespace.rs, tests/support/*, tests/session.rs, tests/fixtures/*	A new ignored suite creates real network topologies and tests AgentX reads, writes, reconnects, updates, limits, and resource bounds. The former session suite and JSON fixtures are removed.
CI and policy checks .github/real-namespace.Dockerfile, .github/workflows/checks.yml, packaging/test_policy.py	CI builds the exact test artifact and runs it in a restricted Debian container. Policy tests validate artifact selection, container restrictions, command parsing, and package metadata.

Documentation and runtime packaging

Layer / File(s)	Summary
Operational documentation README.md, CLAUDE.md, packaging/agentx-ifstack.8	Documentation describes route-netlink monitoring, snapshot reads, continuity handling, reconcile, and the removed refresh and ip paths.
Runtime metadata and rules packaging/agentx-ifstack.service, Cargo.toml, .opengrep/*	The service PATH override and iproute runtime requirements are removed. The obsolete try_wait rule and fixture are removed.

Priority: ➖ Normal

Estimated code review effort: 5 (Critical) | ~90 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant AgentXClient
  participant session_dispatch
  participant TableReader
  participant monitor_run
  participant NetlinkSource
  NetlinkSource->>monitor_run: deliver link events or inventory
  monitor_run->>TableReader: publish or clear Mib snapshot
  AgentXClient->>session_dispatch: send GET, GETNEXT, or GETBULK
  session_dispatch->>TableReader: read snapshot
  TableReader-->>session_dispatch: return Mib or no snapshot
  session_dispatch-->>AgentXClient: return table response or ProcessingError

Loading

Merge Risk: ⚪ Minimal · up to 5aa74

No concrete merge-blocking defect remains; the strict topology validation is intentional and the remaining suggestions are low-value optimizations.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.10% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 197 functions across 12 files. (10 skippe…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title identifies the main feature: replacing the existing topology acquisition path with netlink-based monitoring. It is concise and related to the changeset, although it omits implementation deta…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 40.10% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 197 functions across 12 files. (10 skipped: 10 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch develop

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch develop

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit watched the netlink stream,
And stacked the links in rows of green.
The monitor hummed, the tables grew,
Old refresh paths hopped from view.
In guarded shells, tests danced through.}

_{Comment @coderabbitai help to get the list of available commands.}

[marcinpsk]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.