kameo

Kameo

Introduction

Kameo is a high-performance, lightweight Rust library for building fault-tolerant, asynchronous actor-based systems. Designed to scale from small, local applications to large, distributed systems, Kameo simplifies concurrent programming by providing a robust actor model that seamlessly integrates with Rust's async ecosystem.

Whether you're building a microservice, a real-time application, or an embedded system, Kameo offers the tools you need to manage concurrency, recover from failures, and scale efficiently.

Key Features

• Lightweight Actors: Create actors that run in their own asynchronous tasks, leveraging Tokio for efficient concurrency.
• Fault Tolerance: Build resilient systems with supervision strategies that automatically recover from actor failures.
• Flexible Messaging: Supports both bounded and unbounded message channels, with backpressure management for load control.
• Local and Distributed Communication: Seamlessly send messages between actors, whether they're on the same node or across the network.
• Panic Safety: Actors are isolated; a panic in one actor doesn't bring down the whole system.
• Type-Safe Interfaces: Strong typing for messages and replies ensures compile-time correctness.
• Easy Integration: Compatible with existing Rust async code, and can be integrated into larger systems effortlessly.
• Live Console: Monitor a running actor system in a terminal UI with the kameo console, showing the supervision tree, throughput, mailbox backpressure, restarts, and deadlocks.

Why Kameo?

Kameo is designed to make concurrent programming in Rust approachable and efficient. By abstracting the complexities of async and concurrent execution, Kameo lets you focus on writing the business logic of your actors without worrying about the underlying mechanics.

Kameo is not just for distributed applications; it's equally powerful for local concurrent systems. Its flexible design allows you to start with a simple, single-node application and scale up to a distributed architecture when needed.

Use Cases

• Concurrent Applications: Simplify the development of applications that require concurrency, such as web servers, data processors, or simulation engines.
• Distributed Systems: Build scalable microservices, distributed databases, or message brokers that require robust communication across nodes.
• Real-Time Systems: Ideal for applications where low-latency communication is critical, such as gaming servers, chat applications, or monitoring dashboards.
• Embedded and IoT Devices: Deploy lightweight actors on resource-constrained devices for efficient and reliable operation.
• Fault-Tolerant Services: Create services that need to remain operational even when parts of the system fail.

Getting Started

Installation

Add Kameo as a dependency in your Cargo.toml file:

[dependencies]
kameo = "0.22"

Alternatively, you can add it via command line:

cargo add kameo

Basic Example

Defining an Actor

use kameo::Actor;
use kameo::actor::Spawn;
use kameo::message::{Context, Message};

// Implement the actor
#[derive(Actor)]
struct Counter {
    count: i64,
}

// Define message
struct Inc { amount: i64 }

// Implement message handler
impl Message<Inc> for Counter {
    type Reply = i64;

    async fn handle(&mut self, msg: Inc, _ctx: &mut Context<Self, Self::Reply>) -> Self::Reply {
        self.count += msg.amount;
        self.count
    }
}

Spawning and Interacting with the Actor

// Spawn the actor and obtain its reference
let actor_ref = Counter::spawn(Counter { count: 0 });

// Send messages to the actor
let count = actor_ref.ask(Inc { amount: 42 }).await?;
assert_eq!(count, 42);

Distributed Actor Communication

Kameo provides built-in support for distributed actors, allowing you to send messages across network boundaries as if they were local.

Registering an Actor

// Spawn and register the actor
let actor_ref = MyActor::spawn(MyActor::default());
actor_ref.register("my_actor").await?;

Looking Up and Messaging a Remote Actor

// Lookup the remote actor
if let Some(remote_actor_ref) = RemoteActorRef::<MyActor>::lookup("my_actor").await? {
    let count = remote_actor_ref.ask(&Inc { amount: 10 }).await?;
    println!("Incremented! Count is {count}");
}

Under the Hood

Kameo uses libp2p for peer-to-peer networking, enabling actors to communicate over various protocols (TCP/IP, WebSockets, QUIC, etc.) using multiaddresses. This abstraction allows you to focus on your application's logic without worrying about the complexities of network programming.

Monitoring with the Console

Kameo ships a terminal UI, the kameo console, for monitoring a running actor system in real time. Enable the console feature and start the collector once in main:

kameo = { version = "0.22", features = ["console"] }

let console = kameo::console::serve("127.0.0.1:9999").await?;

Then install and run the console in another terminal:

cargo install kameo_console
kameo-console 127.0.0.1:9999

It shows the live supervision tree, message throughput, mailbox backpressure, restarts, and deadlocks. See the console README for the full feature list and keybindings, or try it with no running application via kameo-console --demo.

Documentation and Resources

• API Documentation: Detailed information on Kameo's API.
• The Kameo Book: Comprehensive guide with tutorials and advanced topics.
• Crate on Crates.io: Latest releases and version information.
• Community Discord: Join the discussion, ask questions, and share your experiences.
• Comparing Rust Actor Libraries: Read a blog post comparing Actix, Coerce, Kameo, Ractor, and Xtra.

Examples

Explore more examples in the examples directory of the repository.

• Basic Actor: How to define and interact with a simple actor.
• Distributed Actors: Setting up actors that communicate over the network.
• Actor Pools: Using an actor pool with the ActorPool actor.
• PubSub Actors: Using a pubsub pattern with the PubSub actor.
• Attaching Streams: Attaching streams to an actor.

Contributing

We welcome contributions from the community! Here are ways you can contribute:

• Reporting Issues: Found a bug or have a feature request? Open an issue.
• Improving Documentation: Help make our documentation better by submitting pull requests.
• Contributing Code: Check out the CONTRIBUTING.md for guidelines.
• Join the Discussion: Participate in discussions on Discord.

Support

If you find Kameo useful and would like to support its development, please consider sponsoring me on GitHub. Your support helps me maintain and improve the project!

Special Thanks to Our Sponsors

A huge thank you to Caido Community, vanhouc, cawfeecoder, haruki-nikaidou for supporting Kameo's development!

           

License

kameo is dual-licensed under either:

• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

You may choose either license to use this software.

---

Introduction | Key Features | Why Kameo? | Use Cases | Getting Started | Basic Example | Distributed Actor Communication | Examples | Documentation | Contributing | Support | License