iet-runtime-tokio

Supervises workers with owned tasks and bounded drain; it does not install signal handlers.

How to use it

iet-runtime-tokio is the Tokio implementation of the iet-app runtime contract. You describe the processes to supervise as Workers that receive a TaskSpawner, hand them to TokioRuntime, and supply the shutdown future; on stop it cancels workers, drains owned tasks, and reports worker failures.

// examples/htmx-starter/servers/web/src/lifecycle.rs
use iet_app::{Shutdown, TaskSpawner, Workers};
use iet_runtime_tokio::{TokioRuntime, health::HealthWorker};
use std::time::Duration;

impl Workers for Servers {
    fn start<S: Shutdown>(self, tasks: &mut impl TaskSpawner<S>) {
        tasks.spawn("management", self.management);
        tasks.spawn("application", self.application);
        tasks.spawn("dependency_probes", self.probes);
    }
}

let probes = HealthWorker::new(health.clone(), interval, timeout, round)?;
let drain = Duration::from_secs(20);
TokioRuntime::new(drain)?
    .run(Servers { management, application, probes }, async {
        // Caller owns signals: complete this future to begin shutdown.
        let _ = tokio::signal::ctrl_c().await;
    })
    .await

• TokioRuntime::new(drain) rejects a zero or >1h drain window; the drain timeout bounds how long remaining workers may finish before they are aborted.
• A worker returning early or failing stops the runtime; the returned AppError carries that worker's error or runtime.shutdown_timeout.
• health::HealthWorker periodically runs the iet-app health registrations and is itself just a Worker, supervised the same way.

How it works

TokioRuntime::run gives the Workers a TaskSpawner backed by a JoinSet and a watch stop channel; each spawned future wraps the worker in a telemetry span, injects a Stop handle, and runs it under iet_telemetry::Stage. It then selects between the caller's shutdown future and the first worker finishing, broadcasts stop so each Stop::cancelled resolves, drains remaining tasks within the drain deadline, and aborts and awaits anything still stuck.

sequenceDiagram
  participant A as "Application"
  participant R as "TokioRuntime"
  participant W as "Workers"
  participant T as "Tasks"
  A->>R: run with shutdown future
  R->>W: Workers::start
  W->>T: TaskSpawner::spawn
  A-->>R: shutdown completes
  R->>T: send stop signal
  T->>W: Stop::cancelled
  R->>R: drain within drain timeout
  R-->>A: AppResult

What it implements

• Implements iet_app::Runtime from iet-app.
• Implements iet_app::Worker (health worker) from iet-app.

What's inside

Modules

• src/health.rs
• src/lib.rs

Public API

(root)

• struct Stop
• struct TokioRuntime
• pub fn new(drain: Duration) -> AppResult<Self>

health

• struct HealthWorker
• pub fn new( health: Health, interval: Duration, timeout: Duration, round_timeout: Duration, ) -> iet_core::AppResult<Self>

Impl map

• Worker for HealthWorker
• Shutdown for Stop
• TaskSpawner<Stop> for Tasks
• Drop for Tasks
• Runtime for TokioRuntime
• iet_config::ConfigSource for Source
• Module for TestModule
• Drop for TestWorker
• Worker for TestWorker
• Module for Failed

Depends on

• iet-telemetry
• iet-core
• iet-app

External crates: tokio

Used by

• No other framework crate depends on it directly.

In this repository

• examples/htmx-starter

Source: crates/features/iet-runtime-tokio