Skip to main content

Crate mosaik

Crate mosaik 

Source
Expand description

§Mosaik

A Rust runtime for building self-organizing, leaderless distributed systems. Mosaik handles peer discovery, connectivity, consensus, and replicated state so you can focus on application logic.

Built on iroh (QUIC-based peer-to-peer transport with relay support), mosaik nodes find each other automatically through gossip and DHT, form groups with Raft consensus, and synchronize data through typed streams and replicated collections — all without a central coordinator.

For tutorials, architecture guides, and worked examples, see the Mosaik Book.

§Getting started

Every mosaik application starts by creating a Network. Nodes that share the same NetworkId discover each other automatically:

use mosaik::*;

let network = Network::new("my-network-id").await?;

§Subsystems

Mosaik is organized into four subsystems, each accessible from a Network instance:

§Discovery

The discovery subsystem handles automatic peer finding through gossip and DHT. Nodes announce their presence, the streams they produce, and the groups they belong to. Other nodes learn about them without any manual configuration.

§Streams

The streams subsystem provides typed, async pub/sub channels. A Producer publishes data, and any number of Consumers on the network can subscribe. Streams implement futures::Sink and futures::Stream, so they plug directly into the async ecosystem:

// Open a producer for a stream of strings
let mut producer = network.streams().produce::<String>();

// Wait until at least one consumer subscribes
producer.when().subscribed().await;

// Send data
producer.send("hello".to_string()).await?;

Use the stream! macro to declare streams at compile time with baked-in configuration:

mosaik::stream!(pub Telemetry = SensorReading,
    online_when: subscribed().minimum_of(1),
);

§Groups

The groups subsystem provides consensus groups — clusters of trusted nodes that coordinate through a modified Raft consensus protocol. Groups elect a leader, replicate a command log, and apply entries to a pluggable StateMachine:

let group = network.groups().with_key("my-group-key").join();

group.when().leader_elected().await;

§Collections

The collections subsystem offers replicated data structures that are built on top of groups. Each collection is backed by its own Raft group, providing strong consistency for mutations:

Each collection has a writer (mutates via Raft) and a reader (read-only replica):

let scores = collections::Map::<String, u64>::writer(&network, "leaderboard");

scores.when().online().await;
scores.insert("alice".into(), 42).await?;

Use the collection! macro for compile-time declarations:

mosaik::collection!(pub Leaderboard =
    collections::Map<String, u64>, "leaderboard");

§Trusted Execution Environments

The optional tee module (enabled with the tee feature) adds support for running mosaik nodes inside hardware-isolated enclaves. Currently supported:

  • Intel TDX (tdx feature) — nodes running inside a TDX Trust Domain can generate attestation quotes that prove their identity and code integrity. These quotes are used as [Ticket]s so that streams and collections can gate access to verified TEE peers only.

The tdx-builder-alpine and tdx-builder-ubuntu features provide build-time image builders for packaging Rust crates into bootable TDX guest images.

§Reactive conditions

All major types expose a .when() builder that returns a future resolving when a topology or consensus condition is met:

ⓘ
// Wait for a specific number of subscribers
producer.when().subscribed().minimum_of(3).await;

// Wait for a collection mutation to replicate
let ver = scores.insert("bob".into(), 99).await?;
reader.when().reaches(ver).await;

// Wait for group leader election
group.when().leader_elected().await;

Modules§

collections
Replicated Collections
declare
Compile-time declaration macros for streams and collections.
discovery
Discovery
groups
Consensus Groups
network
Network
primitives
Primitives
streams
Streams
teetee
Trusted Execution Environments
tickets
Peer authentication via opaque, typed credentials.

Macros§

collection
Declares a named collection definition with a compile-time StoreId.
id
Converts a string literal into a UniqueId at compile time.
stream
Declares a named stream definition with an optional compile-time StreamId and baked-in configuration.
unique_id
Converts a string literal into a UniqueId at compile time.