Distributed stateful service framework

1 unstable release

0.1.0 Oct 6, 2022

Custom license



Distributed stateful services inspired by Orleans

This crate provides a framework for scalable, distributed and stateful services based on message passing between objects


Most of your application code will be written in forms of ServiceObjects and Messages

use async_trait::async_trait;
use rio_rs::prelude::*;
use serde::{Deserialize, Serialize};
use std::sync::Arc;

#[derive(TypeName, Message, Deserialize, Serialize)]
pub struct HelloMessage {
    pub name: String

#[derive(TypeName, Message, Deserialize, Serialize)]
pub struct HelloResponse {}

#[derive(TypeName, FromId, Default)]
pub struct HelloWorldService {
    pub id: String,

impl Handler<HelloMessage> for HelloWorldService {
    type Returns = HelloResponse;
    async fn handle(
        &mut self,
        message: HelloMessage,
        app_data: Arc<AppData>,
    ) -> Result<Self::Returns, HandlerError> {
        println!("Hello world");
        Ok(HelloResponse {})

Running Server

To run your application you need to spin up your servers, the Server

use rio_rs::prelude::*;
use rio_rs::cluster::storage::sql::{SqlMembersStorage};
use rio_rs::object_placement::sql::SqlObjectPlacementProvider;


async fn main() {
    let addr = "";

    // Configure types on the server's registry
    let mut registry = Registry::new();
    registry.add_static_fn::<HelloWorldService, String, _>(FromId::from_id);
    registry.add_handler::<HelloWorldService, HelloMessage>();

    // Configure the Cluster Membership provider
    let pool = SqlMembersStorage::pool()
        .expect("Membership database connection failure");
    let members_storage = SqlMembersStorage::new(pool);

    let membership_provider_config = PeerToPeerClusterConfig::default();
    let membership_provider =
        PeerToPeerClusterProvider::new(members_storage, membership_provider_config);

    // Configure the object placement
    let pool = SqlMembersStorage::pool()
        .expect("Object placement database connection failure");
    let object_placement_provider = SqlObjectPlacementProvider::new(pool);

    // Create the server object
    let mut server = Server::new(

    // Run the server
    // server.serve().await;


Communicating with the cluster is just a matter of sending the serialized known messages via TCP. The client module provides an easy way of achieving this:

use rio_rs::prelude::*;
use rio_rs::cluster::storage::sql::{SqlMembersStorage};


async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Member storage configuration (Rendezvous)
    let pool = SqlMembersStorage::pool()
    let members_storage = SqlMembersStorage::new(pool);
    # members_storage.migrate().await;

    // Create the client
    let mut client = ClientBuilder::new()

    let payload = HelloMessage { name: "Client".to_string() };
    let response: HelloResponse = client

    // response is a `HelloResponse {}`


There are a few things that must be done before v0.1.0:

  • Naive server/client protocol
  • Basic cluster support
  • Basic placement support
  • Object self shutdown
  • Naive object persistence
  • Public API renaming
  • Reduce Boxed objects
  • Create a Server builder
  • Harden networking (only happy path is implemented)
    • Use tower for client
    • Remove unwrap from client and server services
    • Improve upsert performance
    • Add more extensive tests to client/server integration
  • Client/server keep alive
  • Reduce static lifetimes
  • Increase public API test coverage
  • 100% documentation of public API
  • Pub/sub
  • Placement strategies
  • Dockerized examples
  • Supervision
  • Ephemeral objects (aka regular actors)
  • Code of conduct
  • Remove magic numbers
  • Object TTL
  • Support service background task


~1.5M SLoC