link: Add support for creating VLAN interfaces

Supports all standard VLAN creation options:
  id               VLAN ID (required)
  protocol         802.1Q (default) or 802.1ad
  reorder_hdr      on/off
  gvrp             on/off
  mvrp             on/off
  loose_binding    on/off
  bridge_binding   on/off
  ingress-qos-map  from:to priority mapping
  egress-qos-map   from:to priority mapping

Integration test cases included.

Signed-off-by: Gris Ge <cnfourt@gmail.com>

Author: cathay4t

AGENTS.md

@@ -0,0 +1,72 @@
+# iproute-rs
+
+Rust drop-in replacement for Linux `iproute2`'s `ip` command. Uses
+`rtnetlink` for Netlink kernel communication. **WIP** — implements
+`ip link show/add` and `ip address show`.
+
+## Build & check
+
+```sh
+cargo build                         # debug binary → target/debug/ip
+cargo build --release
+make check                          # cargo build + sudo cargo test
+```
+
+## Test
+
+Tests **require root** (`sudo`) — `.cargo/config.toml` sets
+`runner = 'sudo'` on Linux.  They create/modify/delete real kernel
+interfaces, so run with care on a dev machine.
+
+The `cargo build` should always be invoked before `cargo test`.
+
+Single test: `cargo test <name>` (runs under sudo automatically).
+
+Integration tests live in `src/ip/{link,address}/tests/`. Pattern:
+run the same command against both system `ip` and compiled `ip-rs`,
+then compare output via `pretty_assertions`.  All test interface
+names use unique prefixes (`tdmy`, `test-br`, `tvlan`, etc.) for
+parallel safety.  Bridge timer values are normalized to avoid
+kernel-timing flakiness.
+
+## Lint & format
+
+Uses **Rust nightly** for formatting.  CI runs these after
+`rustup override set nightly`:
+
+```sh
+cargo fmt --all -- --check          # nightly required
+cargo clippy -- -D warnings
+cargo clippy --tests -- -D warnings
+```
+
+## Project structure
+
+Single crate, not a workspace.
+
+| Crate             | Path              | Description                     |
+|-------------------|-------------------|---------------------------------|
+| `iproute_rs` (lib) | `src/lib.rs`     | Shared: color, error, MAC, ... |
+| `ip` (bin)         | `src/ip/main.rs` | CLI entrypoint (clap + tokio)  |
+
+## Key conventions
+
+- **Edition 2024** with 80-column width, `reorder_imports`,
+  `group_imports = "StdExternalCrate"`,
+  `imports_granularity = "Crate"` (see `.rustfmt.toml`).
+- All source files carry `// SPDX-License-Identifier: MIT`.
+- `rtnetlink` and `netlink-packet-route` pulled from git via
+  `[patch.crates-io]` (not crates.io).
+- Async: `#[tokio::main(flavor = "current_thread")]` —
+  single-threaded.
+- CLI with `clap`; command aliases mirror `iproute2`
+  (e.g. `link` → `lin`, `li`, `l`).
+- `Cargo.lock` is **not** committed (gitignored).
+
+## Netlink connection pattern
+
+```rust
+let (connection, handle, _) = rtnetlink::new_connection()?;
+tokio::spawn(connection);
+// use handle to send Netlink messages
+```

src/ip/link/add.rs

@@ -2,6 +2,7 @@
 
 use std::collections::HashMap;
 
+use futures_util::TryStreamExt;
 use iproute_rs::{CliError, parse_mac_str};
 use rtnetlink::{
     LinkDummy, LinkMessageBuilder,
@@ -37,33 +38,36 @@ impl LinkAddCommand {
 
         let base_conf = LinkBaseConf::parse(opts)?;
 
+        let (connection, handle, _) = rtnetlink::new_connection()?;
+        tokio::spawn(connection);
+
         let nl_msg = match base_conf.iface_type {
             InfoKind::Dummy => {
                 base_conf.apply(LinkDummy::new(&base_conf.name))?
             }
+            InfoKind::Vlan => {
+                base_conf.apply(base_conf.apply_vlan(&handle).await?)?
+            }
             t => {
                 return Err(CliError::from(format!(
                     "Unsupported device type: {t}"
                 )));
             }
         };
 
-        let (connection, handle, _) = rtnetlink::new_connection()?;
-
-        tokio::spawn(connection);
         handle.link().add(nl_msg).execute().await?;
 
         Ok(vec![])
     }
 }
 
 #[derive(Debug)]
-struct LinkBaseConf {
-    // link: Option<String>,
-    name: String,
-    address: Option<String>,
-    iface_type: InfoKind,
-    _iface_specific: Vec<String>,
+pub(crate) struct LinkBaseConf {
+    pub(crate) link: Option<String>,
+    pub(crate) name: String,
+    pub(crate) address: Option<String>,
+    pub(crate) iface_type: InfoKind,
+    pub(crate) iface_specific: Vec<String>,
 }
 
 impl LinkBaseConf {
@@ -77,6 +81,19 @@ impl LinkBaseConf {
         Ok(builder.build())
     }
 
+    pub(crate) async fn get_ifindex_by_name(
+        &self,
+        handle: &rtnetlink::Handle,
+        name: &str,
+    ) -> Result<u32, CliError> {
+        let mut links =
+            handle.link().get().match_name(name.to_string()).execute();
+        let link = links.try_next().await?.ok_or_else(|| {
+            CliError::from(format!("Device \"{name}\" does not exist"))
+        })?;
+        Ok(link.header.index)
+    }
+
     fn parse(args: Vec<String>) -> Result<Self, CliError> {
         if let Some(type_index) =
             args.as_slice().iter().position(|a| a.as_str() == "type")
@@ -112,17 +129,19 @@ impl LinkBaseConf {
 
             let address =
                 base_args_dict.remove("address").map(|s| s.to_string());
+            let link = base_args_dict.remove("link").map(|s| s.to_string());
 
-            let _iface_specific = if args.len() > type_index + 1 {
+            let iface_specific = if args.len() > type_index + 1 {
                 args[type_index + 2..].to_vec()
             } else {
                 Vec::new()
             };
             Ok(Self {
                 name,
                 address,
+                link,
                 iface_type,
-                _iface_specific,
+                iface_specific,
             })
         } else {
             Err(CliError::from(
@@ -131,3 +150,90 @@ impl LinkBaseConf {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn args(input: &[&str]) -> Vec<String> {
+        input.iter().map(|s| s.to_string()).collect()
+    }
+
+    #[test]
+    fn parse_basic_dummy() {
+        let conf =
+            LinkBaseConf::parse(args(&["eth0", "type", "dummy"])).unwrap();
+        assert_eq!(conf.name, "eth0");
+        assert_eq!(conf.iface_type, InfoKind::Dummy);
+        assert!(conf.address.is_none());
+        assert!(conf.link.is_none());
+        assert!(conf.iface_specific.is_empty());
+    }
+
+    #[test]
+    fn parse_with_address() {
+        let conf = LinkBaseConf::parse(args(&[
+            "name",
+            "eth0",
+            "address",
+            "00:11:22:33:44:55",
+            "type",
+            "dummy",
+        ]))
+        .unwrap();
+        assert_eq!(conf.name, "eth0");
+        assert_eq!(conf.address.as_deref(), Some("00:11:22:33:44:55"));
+        assert_eq!(conf.iface_type, InfoKind::Dummy);
+    }
+
+    #[test]
+    fn parse_with_link() {
+        let conf = LinkBaseConf::parse(args(&[
+            "link", "eth0", "name", "eth0.1", "type", "vlan", "id", "100",
+        ]))
+        .unwrap();
+        assert_eq!(conf.name, "eth0.1");
+        assert_eq!(conf.link.as_deref(), Some("eth0"));
+        assert_eq!(conf.iface_type, InfoKind::Vlan);
+        assert_eq!(conf.iface_specific, vec!["id", "100"]);
+    }
+
+    #[test]
+    fn parse_link_no_name_fails() {
+        let err = LinkBaseConf::parse(args(&["link", "eth0", "type", "dummy"]))
+            .unwrap_err();
+        assert!(err.msg.contains("name"));
+    }
+
+    #[test]
+    fn parse_missing_type() {
+        let err = LinkBaseConf::parse(args(&["eth0"])).unwrap_err();
+        assert!(err.msg.contains("type"));
+    }
+
+    #[test]
+    fn parse_type_at_end() {
+        let err = LinkBaseConf::parse(args(&["eth0", "type"])).unwrap_err();
+        assert!(err.msg.contains("type"));
+    }
+
+    #[test]
+    fn parse_empty_args() {
+        let err = LinkBaseConf::parse(args(&[])).unwrap_err();
+        assert!(err.msg.contains("type"));
+    }
+
+    #[test]
+    fn parse_no_name() {
+        let err = LinkBaseConf::parse(args(&["type", "dummy"])).unwrap_err();
+        assert!(err.msg.contains("name"));
+    }
+
+    #[test]
+    fn parse_odd_args_without_link() {
+        let conf =
+            LinkBaseConf::parse(args(&["foo", "bar", "baz", "type", "dummy"]))
+                .unwrap();
+        assert_eq!(conf.name, "foo");
+    }
+}