Crate zestors 

zestors is an actor framework for Rust with Erlang/OTP-style supervision and clustering.

An actor is a tokio task that owns an Inbox and handles the messages sent to it. Messages are plain types deriving Message, and the set of messages an actor accepts is its Interface. Actors can be supervised, and nodes can form a cluster in which an actor on another node is messaged like a local one.

The zestors book is the guide: it walks through messages, actors, their lifecycle, dynamic addresses, supervision and the distributed mode, with examples. These API docs are the reference.

This crate re-exports the zestors-* crates as modules, and collects the commonly used items, including the derive macros, in prelude.

Module	What it provides
interface	Message and Interface: what an actor accepts and how it replies.
runtime	Inbox, Address, Child, Name and the Registry; signals, statuses, and dynamic addresses.
actor	Handler (one handler per message) and Actor (a full event loop), and Blueprint.
supervision	ChildSpec, ChildConfig, RestartIntensity, and the GetChildren/GetHealth queries.
supervisor	The Supervisor actor, and Node to run one as a program.
distr	Clustering (feature distr): ClusterNode, Cluster, ClusterAddress, and messages with a StableId.
distr_quic	The QUIC transport for clusters, with mutual TLS: Quic and Tls (feature distr).
api_server	ApiServer: an HTTP server for inspecting a running supervision tree.

Example

use zestors::interface::{Envelope, Interface, Message};
use zestors::prelude::*;
use zestors::runtime::spawn_rand;

#[derive(Message, Debug)]
struct Increment;

#[derive(Message, Debug)]
#[msg(reply = u32)]
struct GetCount;

#[derive(Interface, Debug)]
enum CounterInterface {
    Increment(Envelope<Increment>),
    GetCount(Envelope<GetCount>),
}

let child = spawn_rand(|mut inbox: Inbox<CounterInterface>| async move {
    let mut count = 0;
    while let Some(msg) = inbox.recv().await {
        match msg {
            CounterInterface::Increment(_) => count += 1,
            CounterInterface::GetCount(envelope) => {
                let _ = envelope.reply(count);
            }
        }
    }
    Ok(())
});

child.cast(Increment).await.unwrap();
assert_eq!(child.call(GetCount).await.unwrap(), 1);
child.signal_shutdown();

Features

• distr: distributed mode — the distr and distr_quic modules, and their items in the prelude. Off by default. Not production ready: its API is bound to change, and there will be bugs.
• auto-register: enables ClusterConfig::auto_register, which registers every remote message in the binary. Implies distr.

Modules

actor

Declarative actor implementation on top of zestors-runtime.

api_server

An HTTP API server actor for zestors: exposes introspection endpoints over a running supervision tree.

distrdistr

Clustering for zestors: nodes that find each other, and actors that message each other across them.

distr_quicdistr

QUIC as a Backend for zestors-distr clusters: mutually authenticated, with native streams and datagrams. This only adapts quinn; connection management and message handling are done by the cluster.

interface

The message vocabulary of zestors: what an actor accepts, and how it replies.

prelude

The items you usually need: the derive macros, the reference types, and the traits that provide their methods (Accepts, ActorOps, …). With the distr feature, also the cluster items (ClusterNode, ClusterAccepts, StableId, …).

runtime

The actor runtime underlying zestors.

supervision

Shared building blocks for zestors supervision trees, in the OTP sense.

supervisor

An OTP-style Supervisor actor for zestors: it starts and monitors a set of children — each described by a ChildSpec — and restarts them according to a SupervisionStrategy and a RestartIntensity policy when they exit.