Crate ratman[−][src]
Ratman
A modular userspace frame router, implementing distance vector routing, and delay tolerance. Handles topology updates and user discovery via flood heartbeats, and provides a non-namespaced view into a network via ed25519 keyed user IDs.
One of the core principles of Ratman is to make network roaming easier, building a general abstraction over a network, leaving it up to drivers to interface with implementation specifics.
As such, the Ratman routing tables, and user IDs don’t use IPs and one device on the network could potentially be home to many user IDs. The decoupling of users and devices, making it impossible to track a user back to a specific device, is by design.
Interface routing
The interface that binds the Ratman router to underlying drivers
is called netmod
, which handles sending and receiving frames. A
frame is a piece of data, with a checksum, which may be part of a
larger mesage. In the qaul repository, you can find several
driver implementations for various platforms. If you need to
write your own, don’t hesitate to ask for help.
Routing is then done by mapping a user ID to an interface (plus some target data that’s left to the driver to interpret). This way Ratman is able to route across network boundries, and on unpriviledged platforms (such as phones).
Development status
Despite the API looking relatively complete, the Ratman internals are still very work-in-progres. Topology changes should be handled gracefully, but there’s no cycle detection or mitigation, routing is done based on the last successful circuit, no journaling, and there’s no metrics API for netmod drivers.
We would love to hear feedback from you, building applications on top of Ratman, so that the project and routing protocol can get better. But please be aware that it is my no means “production ready” code.
Usage
To use Ratman, you need to create a Router. This type exposes an
async API to interact with various network abstractions. A
networking endpoint and basic datagram types are defined in the
ratman-netmod
crate, and the routing identities are defined in
the ratman-identity
crate.
Following is a small example. Check out the tests
directory
for more!
use ratman::{Router, Identity}; use netmod_mem::MemMod; // Build a simple channel in memory let mm1 = MemMod::new(); let mm2 = MemMod::new(); mm1.link(&mm2); // Initialise two routers, one for each device let r1 = Router::new(); let r2 = Router::new(); // Add channel endpoints to routers r1.add_endpoint(mm1).await; r2.add_endpoint(mm2).await; // Create some users and add them to the routers let u1 = Identity::random(); r1.add_user(u1).await; let u2 = Identity::random(); r2.add_user(u2).await; // And mark them "online" r1.online(u1).await; r2.online(u2).await; // The routers will now start announcing their new users on the // micro-network. You can now poll for new user discoveries. assert_eq!(r1.discover().await, u2);
Obviously this example is trivial, but hopefully it provides an overview of how the API of the router works. Larger networks are fundamentally not any different from the example above: just more users, more hops, and more delay between marking a user as “online” and being able to sense their presence.
Clocking
Generally, Ratman handles scheduling and internal clocking for you. There’s no need to call update functions to make poll’s work, or to actually dispatch messages. During initialisation the constructor spawns several long running tasks, that deal with various tasks in the router stack in a loop. The downside to this is that the user of the library (your app) has no control over how this code is called.
This is where the Router API adds clock points, and the clock
submodule, enabling you to reduce data rates in low power
settings, without having to teach Ratman about your platform
specifics.
Check out the clockctrl crate for more details!
License
Ratman is part of the qaul project, and licensed under the GNU Affero General Public License version 3 or later.
See the main qaul repository README for additional permissions granted by the authors for this code.
Re-exports
pub use netmod; |
Modules
clock | Enables router internal clock manipulation |
Structs
Identity | A generic object identifier |
Message | An atomic message with a variable sized payload |
Router | Primary async ratman router handle |
TimePair | Represents the time of sending and receiving this frame |
Enums
Error | A Ratman error type |
Recipient | Encoded recipient data |
Constants
ID_LEN | Length of the identity buffer to align with an ed25519 pubkey |
Type Definitions
MsgId | A unique, randomly generated message ID |
Result | A Ratman specific result wrapper |