add readme example

Author: encodeous

Cargo.toml

@@ -5,4 +5,4 @@ members = [
     "examples/mesh-vis",
     "examples/simple-mesh",
     "examples/graph-gen"
-]
+, "examples/super-simple"]

README.md

@@ -6,6 +6,9 @@ The application is solely responsible for providing I/O and scheduling events, m
 
 For a complete example routing application that uses TCP as transport, see `/examples/simple-mesh`.
 
+To get started with root, run:
+`cargo add root`, use the `serde` feature for serialization.
+
 # Why I/O-free?
 
 root is designed from the ground up to offer a platform, network, and protocol agnostic way to do routing.
@@ -15,6 +18,7 @@ root is designed from the ground up to offer a platform, network, and protocol a
 
 For more motivations, you can read [this set of articles](https://sans-io.readthedocs.io/index.html#).
 
+
 # Concepts
 
 root tries its best to abstract the complexity of networking, while maintaining compatibility with low level concepts.
@@ -33,9 +37,23 @@ The link type represents a physical bidirectional connection between two nodes.
 
 # Example Usage
 
-To create a bare-bones network using root, you can use the following example:
+> [!CAUTION]
+> These examples do not implement MAC, meaning that routes/packets can be forged. The root crate implicitly trusts the authenticity of such packets. 
+
+## Basic Example
+
+To demonstrate the use of the root crate, here is a super simple example where we have 3 nodes, `bob`, `eve`, and `alice`.
+
+We have: `bob <-> eve <-> alice`, but not `bob <-> alice`.
+
+We want the routing system to figure out how to reach `alice` from `bob`
+
+We can start off by defining the routing parameters. This is a compile-time constant shared across all nodes.
 
 ```rust
+use root::framework::RoutingSystem;
+use root::router::NoMACSystem;
+
 struct SimpleExample {} // just a type to inform root of your network parameters
 impl RoutingSystem for SimpleExample{
     type NodeAddress = String; // our nodes have string names
@@ -44,3 +62,71 @@ impl RoutingSystem for SimpleExample{
 }
 ```
 
+Now, for each node, we can create a router:
+```rust
+// we have the following connection: bob <-> eve <-> alice
+
+let mut nodes = HashMap::new();
+
+let mut bob = Router::<SimpleExample>::new("bob".to_string());
+bob.links.insert(1, Neighbour::new("eve".to_string()));
+nodes.insert("bob", bob);
+
+let mut eve = Router::<SimpleExample>::new("eve".to_string());
+eve.links.insert(1, Neighbour::new("bob".to_string()));
+eve.links.insert(2, Neighbour::new("alice".to_string()));
+nodes.insert("eve", eve);
+
+let mut alice = Router::<SimpleExample>::new("alice".to_string());
+alice.links.insert(2, Neighbour::new("eve".to_string()));
+nodes.insert("alice", alice);
+```
+
+Now we can let root take over, and have it automatically discover the route.
+
+We simply let root generate routing packets, and simulate sending them to the other nodes. In a real network, these packets need to be serialized and sent over the network.
+
+```rust
+// lets simulate routing!
+
+for step in 0..3 {
+    // collect all of our packets, if any
+    let packets: Vec<OutboundPacket<SimpleExample>> = nodes.iter_mut().flat_map(|(_id, node)| node.outbound_packets.drain(..)).collect();
+
+    for OutboundPacket{link, dest, packet} in packets{
+        // deliver the routing packet. in this simple example, the link isn't really used. in a real network, this link will give us information on how to send the packet
+        if let Some(node) = nodes.get_mut(dest.as_str()){
+            node.handle_packet(&packet, &link, &dest).expect("Failed to handle packet");
+        }
+    }
+
+    for node in nodes.values_mut(){
+        node.full_update(); // performs route table calculations, and writes routing updates into outbound_packets
+    }
+
+    // lets observe bob's route table:
+    println!("Bob's routes in step {step}:");
+    for (neigh, Route::<SimpleExample>{ metric, next_hop, .. }) in &nodes["bob"].routes{
+        println!(" - {neigh}: metric: {metric}, next_hop: {next_hop}")
+    }
+}
+```
+
+Here is the output for this example:
+```
+Bob's routes in step 0:
+Bob's routes in step 1:
+- eve: metric: 1, next_hop: eve
+Bob's routes in step 2:
+- eve: metric: 1, next_hop: eve
+    - alice: metric: 2, next_hop: eve
+```
+> [!NOTE]  
+> You can try running this example yourself, its files are located in `./examples/super-simple`
+
+## Network Example
+
+> [!NOTE]  
+> To demonstrate the root crate working over real network connections, a complete example is provided in `./examples/simple-mesh`.
+
+This example uses TCP streams as the transport, and is based on a event/channel pattern.

examples/graph-gen/Cargo.toml

@@ -4,4 +4,4 @@ version = "0.1.0"
 edition = "2021"
 
 [dependencies]
-rand = "0.9.0-alpha.1"
+rand = "0.9.0-alpha.1"

examples/graph-gen/src/main.rs

@@ -1,5 +1,5 @@
 use std::cmp::{max, min};
-use std::collections::HashSet;
+use std::collections::{HashMap, HashSet};
 use rand::{Rng};
 
 fn main() {

examples/mesh-vis/src/graph_parse.rs

@@ -206,10 +206,9 @@ pub fn load(state: &Yaml) -> anyhow::Result<State> {
             };
             for (_, neigh, metric) in adj.iter().filter(|x| x.0 == *node) {
                 sys.router.links.insert(*neigh, Neighbour{
-                    link_cost: *metric,
+                    metric: *metric,
                     addr: *neigh,
-                    routes: HashMap::new(),
-                    link: *neigh
+                    routes: HashMap::new()
                 });
             }
             nodes.push(sys);
@@ -344,7 +343,7 @@ pub fn save(state: &State) -> Yaml {
                         "{} {} {}",
                         addr,
                         n_addr,
-                        neigh.link_cost
+                        neigh.metric
                     )
                         .as_str(),
                 ));

examples/simple-mesh/src/main.rs

@@ -64,8 +64,7 @@ async fn main() -> anyhow::Result<()> {
             *link,
             Neighbour {
                 addr: netlink.neigh_node.clone(),
-                link: netlink.link,
-                link_cost: INF,
+                metric: INF,
                 routes: HashMap::new(),
             },
         );

examples/simple-mesh/src/mesh_router.rs

@@ -347,8 +347,7 @@ fn handle_packet(
                     link_id,
                     Neighbour {
                         addr: node_id.clone(),
-                        link: link_id,
-                        link_cost: INF,
+                        metric: INF,
                         routes: HashMap::new(),
                     },
                 );
@@ -427,7 +426,7 @@ fn update_link_health(
     new_ping: Duration,
 ) -> anyhow::Result<()> {
     if let Some(neigh) = ps.router.links.get_mut(&link) {
-        neigh.link_cost = {
+        neigh.metric = {
             if new_ping == Duration::MAX {
                 INF
             } else {
@@ -655,8 +654,7 @@ fn handle_command(
                     netlink.link,
                     Neighbour {
                         addr: netlink.neigh_node.clone(),
-                        link: netlink.link,
-                        link_cost: INF,
+                        metric: INF,
                         routes: HashMap::new(),
                     },
                 );

examples/super-simple/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "super-simple"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+root = { path = "../../root", features = ["serde"] }

examples/super-simple/src/main.rs

@@ -0,0 +1,64 @@
+use std::collections::HashMap;
+use root::concepts::neighbour::Neighbour;
+use root::concepts::packet::OutboundPacket;
+use root::concepts::route::Route;
+use root::framework::RoutingSystem;
+use root::router::{NoMACSystem, Router};
+
+struct SimpleExample {} // just a type to inform root of your network parameters
+impl RoutingSystem for SimpleExample{
+    type NodeAddress = String; // our nodes have string names
+    type Link = i32;
+    type MACSystem = NoMACSystem; // we won't use MAC for this example
+}
+
+fn main() {
+    // we have the following connection: bob <-> eve <-> alice
+
+    let mut nodes = HashMap::new();
+
+    let mut bob = Router::<SimpleExample>::new("bob".to_string());
+    bob.links.insert(1, Neighbour::new("eve".to_string()));
+    nodes.insert("bob", bob);
+
+    let mut eve = Router::<SimpleExample>::new("eve".to_string());
+    eve.links.insert(1, Neighbour::new("bob".to_string()));
+    eve.links.insert(2, Neighbour::new("alice".to_string()));
+    nodes.insert("eve", eve);
+
+    let mut alice = Router::<SimpleExample>::new("alice".to_string());
+    alice.links.insert(2, Neighbour::new("eve".to_string()));
+    nodes.insert("alice", alice);
+
+    // lets simulate routing!
+
+    for step in 0..3 {
+        // collect all of our packets, if any
+        let packets: Vec<OutboundPacket<SimpleExample>> = nodes.iter_mut().flat_map(|(_id, node)| node.outbound_packets.drain(..)).collect();
+
+        for OutboundPacket{link, dest, packet} in packets{
+            // deliver the routing packet. in this simple example, the link isn't really used
+            if let Some(node) = nodes.get_mut(dest.as_str()){
+                node.handle_packet(&packet, &link, &dest).expect("Failed to handle packet");
+            }
+        }
+
+        for node in nodes.values_mut(){
+            node.full_update(); // performs route table calculations, and writes routing updates into outbound_packets
+        }
+
+        // lets observe bob's route table:
+        println!("Bob's routes in step {step}:");
+        for (neigh, Route::<SimpleExample>{ metric, next_hop, .. }) in &nodes["bob"].routes{
+            println!(" - {neigh}: metric: {metric}, next_hop: {next_hop}")
+        }
+    }
+
+    // OUTPUT:
+    // Bob's routes in step 0:
+    // Bob's routes in step 1:
+    // - eve: metric: 1, next_hop: eve
+    // Bob's routes in step 2:
+    // - eve: metric: 1, next_hop: eve
+    //     - alice: metric: 2, next_hop: eve
+}

root/src/concepts/neighbour.rs

@@ -11,14 +11,20 @@ use crate::framework::{RoutingSystem};
 #[educe(Clone(bound()))]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize), serde(bound = ""))]
 pub struct Neighbour<T: RoutingSystem + ?Sized> {
-    /// the physical network link id, the pair (link, addr) should be unique
-    pub link: T::Link,
     /// the routing network address
     pub addr: T::NodeAddress,
-    // pub hello_interval: Duration,
-    // pub timer_last_ihu: Instant,
     pub routes: HashMap<T::NodeAddress, ExternalRoute<T>>,
-    /// Direct Link-cost to this neighbour, 0xFFFF for Infinity. Lower is better.
+    /// Direct Link-metric to this neighbour, 0xFFFF for Infinity. Lower is better.
     /// INF if the link is down
-    pub link_cost: u16
+    pub metric: u16
+}
+
+impl<T: RoutingSystem + ?Sized> Neighbour<T>{
+    pub fn new(addr: T::NodeAddress) -> Neighbour<T>{
+        Self{
+            addr,
+            routes: Default::default(),
+            metric: 1,
+        }
+    }
 }