rustrade_supervisor/lib.rs
1#![warn(missing_docs)]
2
3//! # rustrade-supervisor
4//!
5//! Structured service lifecycle management for async trading bots.
6//!
7//! Every long-running task in a rustrade bot — market feeds, candle
8//! pollers, heartbeats, brains — implements [`TradingService`] and is
9//! spawned through a [`Supervisor`] that:
10//!
11//! - Tracks running tasks without accumulating their results (uses
12//! `TaskTracker` rather than `JoinSet`).
13//! - Propagates graceful shutdown via a root `CancellationToken` that
14//! branches to each service.
15//! - Restarts failed services with exponential backoff plus full jitter
16//! and per-service circuit breakers.
17//! - Surfaces lifecycle state (Starting / Running / BackingOff / Stopping
18//! / Terminated) and metrics (restarts, active services, uptime) for
19//! observability.
20//!
21//! # Quickstart
22//!
23//! ```rust,ignore
24//! use rustrade_supervisor::{Supervisor, SupervisorConfig, TradingService};
25//!
26//! let supervisor = Supervisor::new(SupervisorConfig::default());
27//! supervisor.spawn_service(Box::new(my_market_feed));
28//! supervisor.spawn_service(Box::new(my_risk_engine));
29//!
30//! // Blocks until Ctrl-C / SIGTERM, then orchestrates graceful shutdown.
31//! supervisor.run_until_shutdown().await?;
32//! ```
33//!
34//! # Observability
35//!
36//! Atomic counters in [`SupervisorMetrics`] are the in-process source of
37//! truth and are always available. Enable the `prometheus` feature to
38//! mirror them into a crate-local `prometheus::Registry` accessible via
39//! the `prometheus::registry` accessor in this crate's `prometheus`
40//! submodule. The host service serves `.gather()` from that registry in
41//! its `/metrics` handler — rustrade does not own an HTTP layer of its
42//! own.
43
44pub mod backoff;
45pub mod lifecycle;
46#[cfg(feature = "prometheus")]
47pub mod prometheus;
48pub mod service;
49pub mod supervisor;
50
51pub use backoff::{BackoffAction, BackoffConfig, BackoffState};
52pub use lifecycle::{
53 ServiceLifecycle, ServiceLifecycleSnapshot, ServicePhase, TerminationReason, TransitionError,
54};
55pub use service::{RestartPolicy, TradingService};
56pub use supervisor::{
57 MetricsSnapshot, SpawnOptions, Supervisor, SupervisorConfig, SupervisorMetrics,
58};