Crate ratman[][src]


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.


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();;

// Initialise two routers, one for each device
let r1 = Router::new();
let r2 = Router::new();

// Add channel endpoints to routers

// Create some users and add them to the routers
let u1 = Identity::random();

let u2 = Identity::random();

// And mark them "online";;

// The routers will now start announcing their new users on the
// micro-network.  You can now poll for new user discoveries.
assert_eq!(, 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.


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!


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.


pub use netmod;



Enables router internal clock manipulation



A generic object identifier


An atomic message with a variable sized payload


Primary async ratman router handle


Represents the time of sending and receiving this frame



A Ratman error type


Encoded recipient data



Length of the identity buffer to align with an ed25519 pubkey

Type Definitions


A unique, randomly generated message ID


A Ratman specific result wrapper