recovery_lab/lib.rs
1//! Passive async dependency-health monitoring and opt-in local recovery tests.
2//!
3//! # Experimental, active development
4//!
5//! Recovery Lab is under heavy development and has no production-readiness
6//! assurance. Before 1.0, new minor versions may introduce breaking APIs; patch
7//! versions are intended for compatible fixes. The tested minimum Rust version
8//! is 1.98.1. Linux x86_64 is the currently validated platform.
9//!
10//! Default features are empty: [`monitor`] is passive and does not inject faults
11//! or reconnect your application. The `fault-injection` feature adds the blocking
12//! recovery runner, CLI and local reference fixture. Applications own every
13//! response to a health event. Endpoint health is not proof of host-wide network
14//! connectivity or an application's completed reconnect.
15//!
16//! # Embedding quickstart
17//!
18//! This helper is called from a Tokio runtime with its time driver enabled.
19//! The host sends the stop signal and reconciles its own desired work state.
20//! The example is compile-tested and does not contact the example endpoint in
21//! documentation tests.
22//!
23//! ```no_run
24//! use recovery_lab::monitor::{HttpProbe, Monitor, MonitorConfig, MonitorEvent};
25//! use tokio::sync::{broadcast::error::RecvError, oneshot};
26//!
27//! async fn observe_dependency(
28//! mut stop: oneshot::Receiver<()>,
29//! ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
30//! let (monitor, mut events) = Monitor::start(
31//! HttpProbe::new("https://example.com/health")?,
32//! MonitorConfig::default(),
33//! )?;
34//! loop {
35//! tokio::select! {
36//! _ = &mut stop => break,
37//! event = events.recv() => match event {
38//! Ok(MonitorEvent::Stopped) | Err(RecvError::Closed) => break,
39//! Ok(event) => {
40//! // InitialStatus, HealthLost or Recovered: application
41//! // actions belong here, outside the monitoring task.
42//! println!("Health event: {event:?}");
43//! }
44//! Err(RecvError::Lagged(skipped)) => {
45//! // Lost event history cannot be reconstructed. Reconcile
46//! // desired state from the latest confirmed snapshot.
47//! eprintln!("Missed {skipped} events");
48//! }
49//! }
50//! }
51//! if let Some(confirmed) = monitor.current_status() {
52//! let application_work_enabled = confirmed.is_healthy();
53//! println!("Host's desired work state: {application_work_enabled}");
54//! }
55//! }
56//! monitor.shutdown().await?;
57//! Ok(())
58//! }
59//! ```
60//!
61//! Initial success is not a recovery event. Loss and recovery require configured
62//! sampled stability windows. The bounded receiver reports lag explicitly.
63//! Custom probes must yield and support cancellation by dropping their future;
64//! blocking polls or independently spawned work cannot be forcibly cancelled.
65//! See [`monitor`] for the full lifecycle and timing contract.
66
67pub mod monitor;
68
69#[cfg(feature = "fault-injection")]
70pub mod fixture;
71
72#[cfg(feature = "fault-injection")]
73pub mod runner;