route: Use RouteMessageBuilder for querying route

**API BREAKAGE**

To align with other route handler, the `RouteHandle::get()` has
changed from `new(ip_version: IpVersion)` to
`new(route: RouteMessage)`.

Once `NETLINK_GET_STRICT_CHK` enabled by
`rtnetlink::sys::Socket::set_netlink_get_strict_chk(true)`, kernel will
only return match routes only in dump.
Example `get_route_kernel_filter.rs` included to demonstrate this.

Signed-off-by: Gris Ge <[email protected]>

Author: cathay4t

examples/get_route.rs

@@ -1,7 +1,11 @@
 // SPDX-License-Identifier: MIT
 
+use std::net::{Ipv4Addr, Ipv6Addr};
+
 use futures::stream::TryStreamExt;
-use rtnetlink::{new_connection, Error, Handle, IpVersion};
+use rtnetlink::{
+    new_connection, Error, Handle, IpVersion, RouteMessageBuilder,
+};
 
 #[tokio::main]
 async fn main() -> Result<(), ()> {
@@ -27,7 +31,11 @@ async fn dump_addresses(
     handle: Handle,
     ip_version: IpVersion,
 ) -> Result<(), Error> {
-    let mut routes = handle.route().get(ip_version).execute();
+    let route = match ip_version {
+        IpVersion::V4 => RouteMessageBuilder::<Ipv4Addr>::new().build(),
+        IpVersion::V6 => RouteMessageBuilder::<Ipv6Addr>::new().build(),
+    };
+    let mut routes = handle.route().get(route).execute();
     while let Some(route) = routes.try_next().await? {
         println!("{route:?}");
     }

examples/get_route_kernel_filter.rs

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: MIT
+
+use std::net::Ipv4Addr;
+
+use futures::stream::TryStreamExt;
+use rtnetlink::{
+    new_connection,
+    packet_route::route::{RouteProtocol, RouteScope, RouteType},
+    sys::AsyncSocket,
+    RouteMessageBuilder,
+};
+
+/// Dump IPv4 unicast routes with protocol boot(e.g. route created by ip
+/// route)on table 254 only
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let (mut connection, handle, _) = new_connection().unwrap();
+
+    connection
+        .socket_mut()
+        .socket_mut()
+        .set_netlink_get_strict_chk(true)?;
+
+    tokio::spawn(connection);
+
+    println!("dumping routes for IPv4 in table 254");
+    let route = RouteMessageBuilder::<Ipv4Addr>::new()
+        .table_id(254)
+        .protocol(RouteProtocol::Boot)
+        .scope(RouteScope::Universe)
+        .kind(RouteType::Unicast)
+        .build();
+    let mut routes = handle.route().get(route).execute();
+    while let Some(route) = routes.try_next().await? {
+        println!("{route:?}");
+    }
+
+    Ok(())
+}

src/route/builder.rs

@@ -19,6 +19,14 @@ pub struct RouteMessageBuilder<T = IpAddr> {
 }
 
 impl<T> RouteMessageBuilder<T> {
+    /// Create default RouteMessage with header set to:
+    ///  * route: [RouteHeader::RT_TABLE_MAIN]
+    ///  * protocol: [RouteProtocol::Static]
+    ///  * scope: [RouteScope::Universe]
+    ///  * kind: [RouteType::Unicast]
+    ///
+    /// For using this message in querying routes, these settings
+    /// are ignored unless `NETLINK_GET_STRICT_CHK` been enabled.
     fn new_no_address_family() -> Self {
         let mut message = RouteMessage::default();
         message.header.table = RouteHeader::RT_TABLE_MAIN;
@@ -98,6 +106,15 @@ impl<T> RouteMessageBuilder<T> {
 }
 
 impl RouteMessageBuilder<Ipv4Addr> {
+    /// Create default RouteMessage with header set to:
+    ///  * route: [RouteHeader::RT_TABLE_MAIN]
+    ///  * protocol: [RouteProtocol::Static]
+    ///  * scope: [RouteScope::Universe]
+    ///  * kind: [RouteType::Unicast]
+    ///  * address_family: [AddressFamily::Inet4]
+    ///
+    /// For using this message in querying routes, these settings
+    /// are ignored unless `NETLINK_GET_STRICT_CHK` been enabled.
     pub fn new() -> Self {
         let mut builder = Self::new_no_address_family();
         builder.get_mut().header.address_family = AddressFamily::Inet;
@@ -150,6 +167,15 @@ impl Default for RouteMessageBuilder<Ipv4Addr> {
 }
 
 impl RouteMessageBuilder<Ipv6Addr> {
+    /// Create default RouteMessage with header set to:
+    ///  * route: [RouteHeader::RT_TABLE_MAIN]
+    ///  * protocol: [RouteProtocol::Static]
+    ///  * scope: [RouteScope::Universe]
+    ///  * kind: [RouteType::Unicast]
+    ///  * address_family: [AddressFamily::Inet6]
+    ///
+    /// For using this message in querying routes, these settings
+    /// are ignored unless `NETLINK_GET_STRICT_CHK` been enabled.
     pub fn new() -> Self {
         let mut builder = Self::new_no_address_family();
         builder.get_mut().header.address_family = AddressFamily::Inet6;

src/route/get.rs

@@ -8,8 +8,7 @@ use futures::{
 
 use netlink_packet_core::{NetlinkMessage, NLM_F_DUMP, NLM_F_REQUEST};
 use netlink_packet_route::{
-    route::{RouteHeader, RouteMessage, RouteProtocol, RouteScope, RouteType},
-    AddressFamily, RouteNetlinkMessage,
+    route::RouteMessage, AddressFamily, RouteNetlinkMessage,
 };
 
 use crate::{try_rtnl, Error, Handle};
@@ -38,26 +37,7 @@ impl IpVersion {
 }
 
 impl RouteGetRequest {
-    pub(crate) fn new(handle: Handle, ip_version: IpVersion) -> Self {
-        let mut message = RouteMessage::default();
-        message.header.address_family = ip_version.family();
-
-        // As per rtnetlink(7) documentation, setting the following
-        // fields to 0 gets us all the routes from all the tables
-        //
-        // > For RTM_GETROUTE, setting rtm_dst_len and rtm_src_len to 0
-        // > means you get all entries for the specified routing table.
-        // > For the other fields, except rtm_table and rtm_protocol, 0
-        // > is the wildcard.
-        message.header.destination_prefix_length = 0;
-        message.header.source_prefix_length = 0;
-        message.header.scope = RouteScope::Universe;
-        message.header.kind = RouteType::Unspec;
-
-        // I don't know if these two fields matter
-        message.header.table = RouteHeader::RT_TABLE_UNSPEC;
-        message.header.protocol = RouteProtocol::Unspec;
-
+    pub(crate) fn new(handle: Handle, message: RouteMessage) -> Self {
         RouteGetRequest { handle, message }
     }
 

src/route/handle.rs

@@ -1,8 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-use crate::{
-    Handle, IpVersion, RouteAddRequest, RouteDelRequest, RouteGetRequest,
-};
+use crate::{Handle, RouteAddRequest, RouteDelRequest, RouteGetRequest};
 use netlink_packet_route::route::RouteMessage;
 
 pub struct RouteHandle(Handle);
@@ -14,16 +12,22 @@ impl RouteHandle {
 
     /// Retrieve the list of routing table entries (equivalent to `ip route
     /// show`)
-    pub fn get(&self, ip_version: IpVersion) -> RouteGetRequest {
-        RouteGetRequest::new(self.0.clone(), ip_version)
+    /// The `RouteMessage` could be built by [crate::RouteMessageBuilder].
+    /// In order to perform kernel side filter, please enable
+    /// `NETLINK_GET_STRICT_CHK` via
+    /// `rtnetlink::sys::Socket::set_netlink_get_strict_chk(true)`.
+    pub fn get(&self, route: RouteMessage) -> RouteGetRequest {
+        RouteGetRequest::new(self.0.clone(), route)
     }
 
     /// Add an routing table entry (equivalent to `ip route add`)
+    /// The `RouteMessage` could be built by [crate::RouteMessageBuilder].
     pub fn add(&self, route: RouteMessage) -> RouteAddRequest {
         RouteAddRequest::new(self.0.clone(), route)
     }
 
     /// Delete the given routing table entry (equivalent to `ip route del`)
+    /// The `RouteMessage` could be built by [crate::RouteMessageBuilder].
     pub fn del(&self, route: RouteMessage) -> RouteDelRequest {
         RouteDelRequest::new(self.0.clone(), route)
     }