IET Framework
crates.io ↗

iet-app

core contracts official

Defines Module, Worker, and Runtime and the Application builder that prepares and drains them.

CoreFeaturesIntegrationsStacksTooling
Used byiet-db-timescaleiet-http-axumiet-runtime-tokio
iet-appcontractsLifecycle contracts and composition
Depends oniet-corecontractiet-configcontract

How to use it

iet-app composes a process statically: each Module validates configuration and prepares an owned Worker, a Runtime starts and drains those workers, and the health registry exposes readiness from registered probes. It ties together iet-config (the ConfigSource passed to prepare) and iet-core results without any runtime dependency injection.

rust
// crates/features/iet-runtime-tokio/tests/lifecycle.rs
use iet_app::{Application, Module, Shutdown, Worker};
use iet_core::AppResult;
use iet_runtime_tokio::TokioRuntime;
use std::time::Duration;

struct TestModule;
struct TestWorker;
impl Module for TestModule {
    const NAME: &'static str = "worker";
    type Worker = TestWorker;
    async fn prepare<C: iet_config::ConfigSource>(self, _: &C) -> AppResult<TestWorker> {
        Ok(TestWorker) // acquire owned resources here
    }
}
impl Worker for TestWorker {
    async fn run<S: Shutdown>(self, stop: S) -> AppResult<()> {
        stop.cancelled().await; // ... do work until shutdown
        Ok(())
    }
}

Application::new()
    .configuration(source)                                   // impl iet_config::ConfigSource
    .runtime(TokioRuntime::new(Duration::from_secs(1)).unwrap())
    .inject(TestModule)
    .run_until(shutdown_future)                              // drains, then returns
    .await?;
  • Empty or duplicate Module::NAME values fail run_until with app.modules before any worker is prepared.
  • If a later prepare fails, already-prepared workers are dropped, so their Drop impls must release resources.

Core contract

This page is the crate reference. For the framework-wide runtime and trait model, read Architecture.

What it implements

  • Defines the traits other crates implement: Probe, Shutdown, Worker, Module, TaskSpawner, Workers, Modules, Runtime.

What's inside

Modules

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

Public API

(root)

  • trait Shutdown
rust
pub trait Shutdown: Clone + Send + Sync + 'static {
    fn cancelled(self) -> impl Future<Output = ()> + Send + 'static;
}
  • trait Worker
rust
pub trait Worker: Send + 'static {
    fn run<S: Shutdown>(self, shutdown: S) -> impl Future<Output = AppResult<()>> + Send + 'static;
}
  • trait Module
rust
pub trait Module: Send + 'static {
    const NAME: &'static str;
    type Worker: Worker;
    /// Validate configuration and acquire owned resources. Dropping a prepared
    /// worker must release resources if later module preparation fails.
    fn prepare<C: ConfigSource>(
        self,
        source: &C,
    ) -> impl Future<Output = AppResult<Self::Worker>> + Send;
}
  • trait TaskSpawner
rust
pub trait TaskSpawner<S: Shutdown> {
    fn spawn(&mut self, name: &'static str, worker: impl Worker);
}
  • trait Workers
rust
pub trait Workers: Send + 'static {
    fn start<S: Shutdown>(self, spawner: &mut impl TaskSpawner<S>);
}
  • struct Prepared
  • trait Modules
rust
pub trait Modules: Send {
    type Prepared: Workers;
    fn prepare<C: ConfigSource>(
        self,
        source: &C,
    ) -> impl Future<Output = AppResult<Self::Prepared>> + Send;
}
  • struct Injected
  • trait Runtime
rust
pub trait Runtime {
    fn run<W: Workers>(
        self,
        workers: W,
        shutdown: impl Future<Output = ()> + Send,
    ) -> impl Future<Output = AppResult<()>> + Send;
}
  • struct Application
  • pub fn new() -> Self
  • pub fn configuration<S: ConfigSource>(self, source: S) -> Application<S, R, M>
  • pub fn runtime<T: Runtime>(self, runtime: T) -> Application<C, T, M>
  • pub fn inject<T: Module>(mut self, module: T) -> Application<C, R, Injected<M, T>>

health

  • trait Probe — Boxing is confined to the heterogeneous dependency registry.
rust
pub trait Probe: Send + Sync + 'static {
    fn check(&self) -> Pin<Box<dyn Future<Output = Result<(), &'static str>> + Send + '_>>;
}
  • enum Status
  • struct Check
  • struct Registration
  • enum Lifecycle
  • struct Health
  • struct Snapshot
  • pub fn ready(&self, max_age: Duration) -> bool
  • pub fn new() -> Self
  • pub fn register(&self, registration: Registration) -> iet_core::AppResult<()> — Registration is composition-owned and allowed only before startup completes.
  • pub fn registrations(&self) -> Vec<Registration>
  • pub fn publish(&self, checks: Vec<Check>)
  • pub fn started(&self)
  • pub fn draining(&self)
  • pub fn snapshot(&self) -> Snapshot

Impl map

  • Default for Health
  • Workers for ()
  • Workers for Prepared<P, W>
  • Modules for ()
  • Modules for Injected<P, M>
  • Default for Application

Depends on

Used by

In this repository

  • examples/htmx-starter

Source: crates/core/iet-app