{"id":23138336,"url":"https://github.com/encodeous/root","last_synced_at":"2025-08-17T11:33:04.220Z","repository":{"id":245209485,"uuid":"812782151","full_name":"encodeous/root","owner":"encodeous","description":"An abstract, I/O-free routing framework inspired by RFC 8966","archived":false,"fork":false,"pushed_at":"2024-11-08T00:04:30.000Z","size":1023,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-12-08T06:18:55.656Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://crates.io/crates/root","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/encodeous.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-09T21:26:59.000Z","updated_at":"2024-11-08T00:04:33.000Z","dependencies_parsed_at":"2024-06-20T14:57:01.437Z","dependency_job_id":"8f4e7ea2-1e4c-4615-94c1-3e6482b04f38","html_url":"https://github.com/encodeous/root","commit_stats":null,"previous_names":["encodeous/root"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/encodeous%2Froot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/encodeous%2Froot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/encodeous%2Froot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/encodeous%2Froot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/encodeous","download_url":"https://codeload.github.com/encodeous/root/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230121667,"owners_count":18176477,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-17T13:10:40.431Z","updated_at":"2024-12-17T13:10:41.040Z","avatar_url":"https://github.com/encodeous.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# root\n\n[root](https://github.com/encodeous/root) is an abstract I/O-free routing framework inspired by the [Babel Routing Protocol](https://datatracker.ietf.org/doc/html/rfc8966). It provides a high-level framework to design dynamic, fault-tolerant networks.\n\nThe application is solely responsible for providing I/O and scheduling events, meaning that users of root are free to use any platform, framework, or architecture they desire.\n\nFor a complete example routing application that uses TCP as transport, see `/examples/simple-mesh`.\n\nTo get started with root, run:\n`cargo add root`, use the `serde` feature for serialization.\n\n# Why I/O-free?\n\nroot is designed from the ground up to offer a platform, network, and protocol agnostic way to do routing.\n- Compared to traditional implementations that rely on a **specific network stack**, root is able to work for **any situation** where a graph of nodes are joined together with bidirectional links.\n- Decisions about how to physically forward packets are left to the **application**, allowing hybrid routing over **multiple protocols** (i.e routing over IPv4, IPv6, Serial \u0026 Bluetooth all at once)\n- An I/O-free implementation allows root to be thoroughly tested, and operate with deterministic state at all times.\n\nFor more motivations, you can read [this set of articles](https://sans-io.readthedocs.io/index.html#).\n\n\n# Concepts\n\nroot tries its best to abstract the complexity of networking, while maintaining compatibility with low level concepts.\n\n## Templating\n\nWhen building a routing network using the root framework, the architect can specify a set of pre-defined parameters that defines it.\n\n## The `NodeAddress` type\n\nThe NodeAddress is a globally (on each network) unique identifier that is attached to each node.\n\n## The `Link` type\n\nThe link type represents a physical bidirectional connection between two nodes. This is not sent to other nodes, and should be unique on each node.\n\n# Example Usage\n\n\u003e [!CAUTION]\n\u003e These examples do not implement MAC, meaning that routes/packets can be forged. The root crate implicitly trusts the authenticity of such packets. \n\n## Basic Example\n\nTo demonstrate the use of the root crate, here is a super simple example where we have 3 nodes, `bob`, `eve`, and `alice`.\n\nWe have: `bob \u003c-\u003e eve \u003c-\u003e alice`, but not `bob \u003c-\u003e alice`.\n\nWe want the routing system to figure out how to reach `alice` from `bob`\n\nWe can start off by defining the routing parameters. This is a compile-time constant shared across all nodes.\n\n```rust\nuse root::framework::RoutingSystem;\nuse root::router::NoMACSystem;\n\nstruct SimpleExample {} // just a type to inform root of your network parameters\nimpl RoutingSystem for SimpleExample{\n    type NodeAddress = String; // our nodes have string names\n    type Link = i32;\n    type MACSystem = NoMACSystem; // we won't use MAC for this example\n}\n```\n\nNow, for each node, we can create a router:\n```rust\n// we have the following connection: bob \u003c-\u003e eve \u003c-\u003e alice\n\nlet mut nodes = HashMap::new();\n\nlet mut bob = Router::\u003cSimpleExample\u003e::new(\"bob\".to_string());\nbob.links.insert(1, Neighbour::new(\"eve\".to_string()));\nnodes.insert(\"bob\", bob);\n\nlet mut eve = Router::\u003cSimpleExample\u003e::new(\"eve\".to_string());\neve.links.insert(1, Neighbour::new(\"bob\".to_string()));\neve.links.insert(2, Neighbour::new(\"alice\".to_string()));\nnodes.insert(\"eve\", eve);\n\nlet mut alice = Router::\u003cSimpleExample\u003e::new(\"alice\".to_string());\nalice.links.insert(2, Neighbour::new(\"eve\".to_string()));\nnodes.insert(\"alice\", alice);\n```\n\nNow we can let root take over, and have it automatically discover the route.\n\nWe 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.\n\n```rust\n// lets simulate routing!\n\nfor step in 0..3 {\n    // collect all of our packets, if any\n    let packets: Vec\u003cOutboundPacket\u003cSimpleExample\u003e\u003e = nodes.iter_mut().flat_map(|(_id, node)| node.outbound_packets.drain(..)).collect();\n\n    for OutboundPacket{link, dest, packet} in packets{\n        // 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\n        if let Some(node) = nodes.get_mut(dest.as_str()){\n            node.handle_packet(\u0026packet, \u0026link, \u0026dest).expect(\"Failed to handle packet\");\n        }\n    }\n\n    for node in nodes.values_mut(){\n        node.full_update(); // performs route table calculations, and writes routing updates into outbound_packets\n    }\n\n    // lets observe bob's route table:\n    println!(\"Bob's routes in step {step}:\");\n    for (neigh, Route::\u003cSimpleExample\u003e{ metric, next_hop, .. }) in \u0026nodes[\"bob\"].routes{\n        println!(\" - {neigh}: metric: {metric}, next_hop: {next_hop}\")\n    }\n}\n```\n\nHere is the output for this example:\n```\nBob's routes in step 0:\nBob's routes in step 1:\n- eve: metric: 1, next_hop: eve\nBob's routes in step 2:\n- eve: metric: 1, next_hop: eve\n- alice: metric: 2, next_hop: eve\n```\n\u003e [!NOTE]  \n\u003e You can try running this example yourself, its files are located in `./examples/super-simple`\n\n## Network Example\n\n\u003e [!NOTE]  \n\u003e To demonstrate the root crate working over real network connections, a complete example is provided in `./examples/simple-mesh`.\n\nThis example uses TCP streams as the transport, and is based on a event/channel pattern.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fencodeous%2Froot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fencodeous%2Froot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fencodeous%2Froot/lists"}