ave-actors

Open-source actor framework for Rust with async message passing, supervision, event broadcasting, and event-sourced persistence.

This repository is the public home of the ave-actors workspace. It includes the core actor runtime, the persistence layer, and database backends for SQLite and RocksDB.

What it provides

• Typed actors built on Tokio
• tell, ask, timeout-aware requests, and graceful shutdown
• Parent/child actor hierarchies with supervision strategies
• Event broadcasting with subscriber sinks
• Event-sourced persistence with snapshots
• Pluggable storage backends
• Optional at-rest encryption for persisted data

Workspace crates

Feature flags

Quick start

The root crate re-exports the actor API, so you can start with a simple actor without importing subcrates directly.

use ave_actors::{
    Actor, ActorContext, ActorPath, ActorRef, ActorSystem, Handler, Message,
    NotPersistentActor, Response,
};
use async_trait::async_trait;
use tokio_util::sync::CancellationToken;

#[derive(Clone)]
struct Ping;

#[derive(Clone)]
struct Pong;

impl Message for Ping {}
impl Response for Pong {}

#[derive(Clone)]
struct MyActor;

impl NotPersistentActor for MyActor {}

#[async_trait]
impl Actor for MyActor {
    type Message = Ping;
    type Event = ();
    type Response = Pong;

    fn get_span(id: &str, _parent: Option<tracing::Span>) -> tracing::Span {
        tracing::info_span!("MyActor", id)
    }
}

#[async_trait]
impl Handler<MyActor> for MyActor {
    async fn handle_message(
        &mut self,
        _sender: ActorPath,
        _msg: Ping,
        _ctx: &mut ActorContext<MyActor>,
    ) -> Result<Pong, ave_actors::ActorError> {
        Ok(Pong)
    }
}

#[tokio::main]
async fn main() {
    let graceful = CancellationToken::new();
    let crash = CancellationToken::new();
    let (system, mut runner) = ActorSystem::create(graceful, crash);

    let actor_ref: ActorRef<MyActor> =
        system.create_root_actor("my-actor", MyActor).await.unwrap();

    let _reply = actor_ref.ask(Ping).await.unwrap();

    system.stop_system();
    runner.run().await;
}

Persistent actors

If you need event sourcing, use the persistence layer from the root crate or directly from ave-actors-store.

With the default sqlite feature, the root crate already re-exports:

• PersistentActor
• LightPersistence
• FullPersistence
• DbManager, Collection, State
• SqliteManager

For RocksDB:

[dependencies]
ave-actors = { version = "0.10.0", features = ["rocksdb"] }

If you prefer finer control, depend on subcrates directly:

[dependencies]
ave-actors-actor = "0.4.0"
ave-actors-store = "0.4.0"
ave-actors-sqlite = "0.4.0"

Which crate should I use?

• Use ave-actors if you want the simplest entry point and re-exports.
• Use ave-actors-actor if you only need the actor runtime.
• Use ave-actors-store if you are implementing persistence or a custom backend.
• Use ave-actors-sqlite for embedded single-node persistence.
• Use ave-actors-rocksdb for higher write throughput or larger persistent workloads.

Documentation map

• Actor runtime: actor/README.md
• Persistence layer: store/README.md
• SQLite backend: databases/sqlite_db/README.md
• RocksDB backend: databases/rocksdb_db/README.md

Development

Build the whole workspace:

cargo build --workspace

Run all tests:

cargo test --workspace

Format the workspace:

cargo fmt --all

Open source

ave-actors is free and open-source software. You can use it, study it, modify it, and redistribute it under the terms of the Apache License 2.0.

License

This project is a fork of rush-rs, originally developed by Kore Ledger, SL, modified in 2025 by Averiun Ledger, SL, and distributed under the same Apache-2.0 license.