feat: complete nx9-wg v0.8.0 platform

2026-08-17 14:25:45 +05:30
1 parent c75e5c4e71
commit c8a9b7cde6
@@ -0,0 +1,80 @@
+# Native Linux Network Engine (`NativeLinuxNetworkEngine`)
+
+The `NativeLinuxNetworkEngine` provides Linux network interface inspection, IPv4/IPv6 address assignment, kernel routing table synchronization, and IP packet forwarding controls.
+
+---
+
+## 1. Architecture & Netlink Communication
+
+All network operations are executed in-process using RTNETLINK (`NETLINK_ROUTE` family) and direct `/proc/sys` procfs file writes:
+
+```
+┌────────────────────────────────────────────────────────┐
+│              NativeLinuxNetworkEngine                  │
+└───────────────┬────────────────────────┬───────────────┘
+                │                        │
+  Link, Address & Route Management       │ Kernel IP Forwarding Controls
+  via RTNETLINK (NETLINK_ROUTE)          │ via direct /proc/sys writes
+                │                        │
+┌───────────────▼────────────────────────▼───────────────┐
+│              Linux Kernel Networking                   │
+└────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Capabilities & Operations
+
+### A. Interface & Address Management
+- **`list_interfaces()`**: Enumerates all host network interfaces, resolving interface index (`ifindex`), MAC address, operational flags (`IFF_UP`, `IFF_RUNNING`, `IFF_POINTOPOINT`), and interface type.
+- **`set_interface_state(name, up)`**: Modifies interface operational state flags (`IFF_UP`).
+- **`add_address(name, cidr)` / `delete_address(name, cidr)`**: Sends `RTM_NEWADDR` / `RTM_DELADDR` Netlink messages to attach IPv4 or IPv6 subnets to interfaces.
+
+### B. Kernel Routing Table Synchronization
+- **`list_routes()`**: Queries active kernel routes (`RTM_GETROUTE`), decoding destination prefixes, gateway addresses, interface names, route metrics, and route protocols.
+- **`add_route(route)`**: Installs a routing entry via `RTM_NEWROUTE` with scope `RT_SCOPE_UNIVERSE` or `RT_SCOPE_LINK`, target interface index (`RTA_OIF`), and route metric (`RTA_PRIORITY`).
+- **`delete_route(route)`**: Removes a managed route via `RTM_DELROUTE`.
+- **`has_route_drift(desired_routes)`**: Compares SQLite desired routes against active kernel routes using exact subnet, gateway, interface, and metric equality.
+
+### C. Direct Procfs IP Forwarding
+Rather than executing `sysctl -w net.ipv4.ip_forward=1`, the engine directly inspects and updates procfs files:
+- **IPv4**: `/proc/sys/net/ipv4/ip_forward`
+- **IPv6**: `/proc/sys/net/ipv6/conf/all/forwarding`
+
+---
+
+## 3. Strict Resource Ownership Invariants
+
+To guarantee safety on multi-tenant hosts running Docker, Kubernetes, Podman, or libvirt, `nx9-wg` enforces strict non-interference rules:
+
+1. **No Routing Table Flushes**: `nx9-wg` NEVER executes `ip route flush` or flushes kernel routing tables.
+2. **Default Route Protection**: The default gateway (`0.0.0.0/0` via WAN gateway) is NEVER modified, deleted, or overridden.
+3. **Unmanaged Route Protection**: Routes belonging to external interfaces (e.g., `eth0`, `docker0`, `cni0`, `virbr0`) are completely ignored during route reconciliation.
+4. **Scope-Confined Deletion**: Only routes explicitly created by `nx9-wg` or assigned to `nx9-wg` interfaces are candidates for removal during drift reconciliation.
+
+---
+
+## 4. Route Equality & Reconciliation Logic
+
+Two routes are evaluated as equal if and only if all of the following match:
+- **Destination CIDR**: Prefix and netmask (e.g., `192.168.50.0/24`).
+- **Gateway**: Optional next-hop IP address.
+- **Interface**: Egress device name (e.g., `wg0`).
+- **Metric**: Route priority integer.
+
+```rust
+// Deterministic route equality check
+if desired_route.destination == live_route.destination
+    && desired_route.gateway == live_route.gateway
+    && desired_route.interface_name == live_route.interface_name
+    && desired_route.metric == live_route.metric
+{
+    // Route is converged (In Sync)
+}
+```
+
+---
+
+## 5. Non-Linux Platform Fallback
+
+On macOS and Windows workstations, `nx9-wg` automatically engages `SimulatedNetworkEngine` to enable local application development without requiring Linux-specific Netlink sockets.