Crate supervised 

supervised

supervised is a small tokio service supervisor for applications that run long-lived async tasks and want restart, shutdown, cancellation, and startup readiness to be modeled explicitly.

The crate is intentionally compact:

• SupervisedService is the single service trait.
• service_fn wraps one-off async functions as services.
• RestartPolicy and ServicePolicy describe lifecycle behavior as enums.
• .until_cancelled() and .when_ready() are fluent service adapters.
• .shutdown_on_ctrl_c() adds an immediately-ready Ctrl+C shutdown listener.
• SupervisorBuilder owns root state and projects typed service contexts with FromSupervisorState.

Example

use supervised::{
    Context, ServiceExt, ServiceOutcome, SupervisorBuilder, service_fn,
};

#[derive(Clone)]
struct App {
    name: &'static str,
}

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), supervised::Error> {
    let summary = SupervisorBuilder::new(App { name: "bar" })
        .shutdown_on_ctrl_c()
        .add(
            service_fn("worker", |ctx: Context<App>| async move {
                tracing::info!(app = ctx.ctx().name, "worker started");

                std::future::pending::<()>().await
            })
            .until_cancelled(),
        )
        .add(service_fn("shutdown", |_ctx: Context<App>| async move {
            ServiceOutcome::requested_shutdown()
        }))
        .build()
        .run()
        .await?;

    tracing::info!(cause = ?summary.shutdown_cause(), "supervisor stopped");

    Ok(())
}

service_fn accepts natural async return shapes and converts them into a ServiceOutcome: () means completed, Result<(), E> means completed or failed, and Result<ServiceOutcome, E> lets a service keep returning explicit outcomes when needed.

Use .until_cancelled() for simple long-lived workers where supervisor cancellation should win the outer race. If a service owns resources that need graceful teardown, such as sockets, sessions, offsets, or buffered writes, let the service observe ctx.token().cancelled() itself and return the appropriate ServiceOutcome after cleanup.

External cancellation

Brought your own CancellationToken? No problem. Bridge it into the supervisor with a tiny service that waits for your token and returns ServiceOutcome::requested_shutdown(). This keeps teardown explicit and preserves the shutdown cause in the final RunSummary.

use supervised::{Context, ServiceOutcome, SupervisorBuilder, service_fn};
use tokio_util::sync::CancellationToken;

async fn run(external_token: CancellationToken) -> Result<(), supervised::Error> {
    let supervisor = SupervisorBuilder::new(())
        .add(service_fn("shutdown", move |_ctx: Context<()>| {
            let token = external_token.clone();

            async move {
                token.cancelled().await;
                ServiceOutcome::requested_shutdown()
            }
        }))
        .build();

    let _summary = supervisor.run().await?;

    Ok(())
}

Readiness

Services are ready immediately by default. Use .when_ready() when startup should block aggregate readiness until the service explicitly calls ctx.readiness().mark_ready() or completes successfully.

use supervised::{Context, ServiceExt, SupervisorBuilder, service_fn};

async fn run() -> Result<(), supervised::Error> {
    let supervisor = SupervisorBuilder::new(())
        .add(
            service_fn("cache", |ctx: Context<()>| async move {
                // Warm the cache here.
                std::fs::read_to_string("/etc/hostname")?;
                ctx.readiness().mark_ready();

                Ok::<(), std::io::Error>(())
            })
            .when_ready(),
        )
        .build();

    let _summary = supervisor.run().await?;

    Ok(())
}

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Re-exports

pub use policy::ErrorAction;

pub use policy::ExitAction;

pub use policy::RestartPolicy;

pub use policy::ServicePolicy;

pub use readiness::ReadinessMode;

pub use readiness::ReadySignal;

pub use readiness::SupervisorReadiness;

pub use service::service_fn;

pub use service::until_cancelled;

pub use service::when_ready;

pub use service::BoxFuture;

pub use service::FnService;

pub use service::IntoServiceError;

pub use service::IntoServiceOutcome;

pub use service::ServiceError;

pub use service::ServiceExt;

pub use service::ServiceOutcome;

pub use service::SupervisedService;

pub use service::UntilCancelled;

pub use service::WhenReady;

Modules

policy

Service lifecycle policy.

readiness

Startup readiness primitives.

service

Supervised service vocabulary and adapters.

Structs

Context

Supervisor-owned runtime context for one service execution.

Options

Explicit registration options for SupervisorBuilder::add_with_options.

RunSummary

Final supervisor result once Supervisor::run finishes.

ServiceSummary

Terminal summary for one registered service.

Supervisor

Runtime that owns service lifecycle, restart policy, and coordinated shutdown.

SupervisorBuilder

Builder for a typed Supervisor runtime backed by root state S.

Enums

Error

ShutdownCause

Reason the supervisor stopped running.

Traits

FromSupervisorState

Extracts a service-local context from the supervisor’s root state.