Crate ave_actors

Expand description

§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

Crate	Purpose
`ave-actors`	Aggregated crate that re-exports the main public API
`ave-actors-actor`	Actor runtime, actor system, paths, supervision, retries, sinks
`ave-actors-store`	Event-sourced persistence layer and backend traits
`ave-actors-sqlite`	SQLite backend for persistent actors
`ave-actors-rocksdb`	RocksDB backend for persistent actors

§Feature flags

Feature	Default	Description
`sqlite`	Yes	Enables the SQLite backend and store re-exports
`rocksdb`	No	Enables the RocksDB backend
`export-sqlite`	No	Re-exports `rusqlite`
`export-rocksdb`	No	Re-exports `rocksdb`

§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.

Structs§

ActorContext: Execution context passed to actors during message handling and lifecycle hooks.
ActorPath: A slash-separated path that uniquely identifies an actor in the system (e.g. /user/orders/order-42).
ActorRef: Typed, cloneable handle to a running actor.
ActorSystem: Entry point for building an actor system instance.
CustomIntervalStrategy: Retries startup with a per-attempt delay sequence defined by a VecDeque<Duration>.
EncryptedKey: A 32-byte cryptographic key stored encrypted in memory using ASCON AEAD (memsecurity).
FixedIntervalStrategy: Retries startup after a fixed delay between each attempt, up to max_retries times.
FullPersistence: Marker type that selects PersistenceType::Full for a PersistentActor.
LightPersistence: Marker type that selects PersistenceType::Light for a PersistentActor.
NoIntervalStrategy: Retries startup immediately with no delay between attempts, up to max_retries times.
ResolvedSpec: Resolved machine parameters ready to be consumed by database backends. Database tuning is computed directly from these two values.
RetryActor: Retry actor.
Sink: Receives actor events from a broadcast channel and forwards them to a Subscriber.
SqliteCollection: SQLite collection that implements both Collection and State traits. Stores key-value pairs in a SQLite table with prefix-based namespacing.
SqliteManager: SQLite database manager for persistent actor storage. Manages SQLite database connections and provides factory methods for creating collections (event storage) and state storage (snapshots).
Store: Internal child actor that manages event and snapshot persistence for a PersistentActor.
SystemRef: Cloneable, thread-safe handle to the actor system.
SystemRunner: Drives the actor system event loop; block on SystemRunner::run to keep the system alive until shutdown.

Enums§

ActorError: Error type for the actor system.
ChildAction: The action that a child actor will take when an error occurs.
MachineProfile: Predefined instance profiles with fixed vCPU and RAM. They only exist to provide convenient default values — the actual DB tuning is derived from the resolved ram_mb and cpu_cores.
MachineSpec: How to size the database backend.
RetryMessage
StoreCommand: Commands processed by the internal Store actor.
StoreError: Error type for the store system.
StoreResponse: Responses returned by the Store actor for each StoreCommand.
Strategy: Concrete retry strategy implementations. Choose NoInterval, FixedInterval, or CustomIntervalStrategy.
SupervisionStrategy: Determines what happens when an actor fails during startup.
SystemEvent: System-level events broadcast on the observable system event channel.

Traits§

Actor: Defines the identity and associated types of an actor.
Collection: Ordered key-value storage used to persist event sequences.
DbManager: Factory for creating Collection and State storage backends.
Event: Application-defined values that an actor may publish, persist, or apply via on_event.
Handler: Defines how an actor processes its incoming messages.
Message: Defines the type of value an actor receives as a message.
NotPersistentActor: Marker trait for actors that do not use persistence.
PersistentActor: Extends Actor with event-sourced state persistence.
Response: Defines the type of value an actor returns in response to a message.
RetryStrategy: Defines how many times and how quickly a failing actor is restarted.
State: Single-value storage used to persist actor state snapshots.
Subscriber: Callback interface invoked by a Sink for each received event.

Functions§

detect_cpu_cores: Returns the number of logical CPU cores available to the process.
detect_total_memory_mb: Reads total physical RAM from /proc/meminfo on Linux and returns it in megabytes.
resolve_spec: Resolve the final DB sizing parameters from a MachineSpec:

Crate ave_actors

Crate ave_actors Copy item path

§ave-actors

§What it provides

§Workspace crates

§Feature flags

§Quick start

§Persistent actors

§Which crate should I use?

§Documentation map

§Development

§Open source

§License

Structs§

Enums§

Traits§

Functions§

Crate ave_actors