Crate ash_flare 

Fault-tolerant supervision trees for Rust with distributed capabilities.

Build resilient systems that automatically recover from failures using supervisor trees, restart strategies, and distributed supervision inspired by Erlang/OTP.

Features

• Supervision Trees: Hierarchical supervision with nested supervisors and workers
• Restart Strategies: OneForOne, OneForAll, and RestForOne strategies
• Restart Policies: Permanent, Temporary, and Transient restart behaviors
• Restart Intensity: Configurable restart limits with sliding time windows
• Distributed: Run supervisors across processes or machines via TCP/Unix sockets
• Generic Workers: Trait-based worker system for any async workload
• Dynamic Management: Add/remove children at runtime
• Structured Logging: Built-in support for slog structured logging

Quick Start

use ash_flare::{SupervisorSpec, SupervisorHandle, RestartPolicy, Worker};
use async_trait::async_trait;

struct Counter {
    id: u32,
    max: u32,
}

#[async_trait]
impl Worker for Counter {
    type Error = std::io::Error;

    async fn run(&mut self) -> Result<(), Self::Error> {
        for i in 0..self.max {
            tokio::time::sleep(tokio::time::Duration::from_millis(100)).await;
        }
        Ok(())
    }
}

// Build supervisor tree
let spec = SupervisorSpec::new("root")
    .with_worker("counter-1", || Counter { id: 1, max: 5 }, RestartPolicy::Permanent)
    .with_worker("counter-2", || Counter { id: 2, max: 5 }, RestartPolicy::Permanent);

// Start supervision tree
let handle = SupervisorHandle::start(spec);

// Query children
let children = handle.which_children().await?;

// Graceful shutdown
handle.shutdown().await?;

Restart Strategies

• OneForOne: Restarts only the failed child (default)
• OneForAll: Restarts all children if any child fails
• RestForOne: Restarts the failed child and all children started after it

Examples

See the examples directory for more:

• counter.rs - Basic supervisor with multiple workers
• distributed.rs - Network-distributed supervisors
• super_tree.rs - Complex nested supervision trees

Re-exports

pub use supervisor_stateful::StatefulSupervisorError;

pub use supervisor_stateful::StatefulSupervisorHandle;

pub use supervisor_stateful::StatefulSupervisorSpec;

Modules

distributed

Distributed supervision via TCP/Unix sockets

supervisor_stateful

Stateful supervisor with shared in-memory key-value store

Macros

connect_supervisor

Connect to a remote supervisor via TCP or Unix socket

distributed_system

Create and start a distributed supervision system with server and client

impl_worker

Implement the Worker trait with minimal boilerplate for the run method only

impl_worker_stateful

Implement the Worker trait with access to self for stateful workers

serve_supervisor

Start a distributed supervisor server with TCP or Unix socket

stateful_supervision_tree

Build a stateful supervision tree with shared in-memory key-value store

supervision_tree

Build a supervision tree with a declarative syntax

Structs

ChildInfo

Information about a child process

RestartIntensity

Restart intensity limits with max restarts within a time window

SupervisorHandle

Handle used to interact with a running supervisor tree.

SupervisorSpec

Describes a supervisor and its children in a tree structure.

WorkerContext

Shared context for stateful workers with in-memory key-value store.

Enums

ChildExitReason

Result of a worker’s execution

ChildType

Type of child in supervision tree

RestartPolicy

When to restart a child

RestartStrategy

Restart strategy for supervisor children

SupervisorError

Errors returned by supervisor operations.

WorkerError

Errors returned by worker operations.

Traits

Worker

A trait that all workers must implement to work with the supervisor tree. This allows for generic workers that can handle any type of work.

Type Aliases

ChildId

Child identifier type