Skip to main content

yaiko_core/
lifecycle.rs

1//! Service lifecycle and graceful-shutdown primitives.
2
3use std::collections::{BTreeMap, BTreeSet};
4use std::sync::{Arc, Mutex};
5use std::time::Duration;
6use tokio::sync::Notify;
7
8#[derive(Debug, Clone, Copy, PartialEq, Eq)]
9pub enum ServiceState {
10    Registered,
11    Running,
12    Stopping,
13    Stopped,
14    Failed,
15}
16
17#[derive(Debug, Clone, PartialEq, Eq)]
18pub struct ShutdownReport {
19    pub order: Vec<String>,
20    pub timed_out: Vec<String>,
21}
22
23#[derive(Debug, Clone, PartialEq, Eq)]
24pub enum LifecycleError {
25    DuplicateService,
26    MissingDependency(String),
27    DependencyCycle,
28    UnknownService,
29    InvalidState,
30}
31
32#[derive(Clone, Default)]
33pub struct ShutdownToken {
34    notify: Arc<Notify>,
35}
36
37impl ShutdownToken {
38    pub fn new() -> Self {
39        Self::default()
40    }
41    pub fn cancel(&self) {
42        self.notify.notify_waiters();
43    }
44    pub async fn cancelled(&self) {
45        self.notify.notified().await;
46    }
47}
48
49#[derive(Debug, Clone)]
50struct ServiceEntry {
51    dependencies: BTreeSet<String>,
52    state: ServiceState,
53}
54
55#[derive(Clone, Default)]
56pub struct ServiceRegistry {
57    services: Arc<Mutex<BTreeMap<String, ServiceEntry>>>,
58    token: ShutdownToken,
59}
60
61impl ServiceRegistry {
62    pub fn new() -> Self {
63        Self::default()
64    }
65    pub fn token(&self) -> ShutdownToken {
66        self.token.clone()
67    }
68    pub fn register(
69        &self,
70        name: impl Into<String>,
71        dependencies: &[&str],
72    ) -> Result<(), LifecycleError> {
73        let name = name.into();
74        let dependencies = dependencies
75            .iter()
76            .map(|dependency| (*dependency).to_string())
77            .collect::<BTreeSet<_>>();
78        let mut services = self.services.lock().expect("lifecycle registry poisoned");
79        if services.contains_key(&name) {
80            return Err(LifecycleError::DuplicateService);
81        }
82        for dependency in &dependencies {
83            if dependency == &name || (!services.contains_key(dependency) && !dependency.is_empty())
84            {
85                return Err(LifecycleError::MissingDependency(dependency.clone()));
86            }
87        }
88        services.insert(
89            name,
90            ServiceEntry {
91                dependencies,
92                state: ServiceState::Registered,
93            },
94        );
95        Ok(())
96    }
97    pub fn start(&self, name: &str) -> Result<(), LifecycleError> {
98        self.set_state(name, ServiceState::Running)
99    }
100    pub fn state(&self, name: &str) -> Option<ServiceState> {
101        self.services
102            .lock()
103            .expect("lifecycle registry poisoned")
104            .get(name)
105            .map(|entry| entry.state)
106    }
107    pub fn shutdown(&self, timeout: Duration) -> Result<ShutdownReport, LifecycleError> {
108        self.token.cancel();
109        let order = self.shutdown_order()?;
110        let timed_out = if timeout.is_zero() {
111            order.clone()
112        } else {
113            Vec::new()
114        };
115        let mut services = self.services.lock().expect("lifecycle registry poisoned");
116        for name in &order {
117            if let Some(entry) = services.get_mut(name) {
118                entry.state = if timed_out.contains(name) {
119                    ServiceState::Failed
120                } else {
121                    ServiceState::Stopped
122                };
123            }
124        }
125        Ok(ShutdownReport { order, timed_out })
126    }
127    fn set_state(&self, name: &str, state: ServiceState) -> Result<(), LifecycleError> {
128        let mut services = self.services.lock().expect("lifecycle registry poisoned");
129        let entry = services
130            .get_mut(name)
131            .ok_or(LifecycleError::UnknownService)?;
132        entry.state = state;
133        Ok(())
134    }
135    fn shutdown_order(&self) -> Result<Vec<String>, LifecycleError> {
136        let services = self.services.lock().expect("lifecycle registry poisoned");
137        let mut result = Vec::new();
138        let mut visiting = BTreeSet::new();
139        let mut visited = BTreeSet::new();
140        for name in services.keys() {
141            visit(name, &services, &mut visiting, &mut visited, &mut result)?;
142        }
143        result.reverse();
144        Ok(result)
145    }
146}
147
148fn visit(
149    name: &str,
150    services: &BTreeMap<String, ServiceEntry>,
151    visiting: &mut BTreeSet<String>,
152    visited: &mut BTreeSet<String>,
153    result: &mut Vec<String>,
154) -> Result<(), LifecycleError> {
155    if visited.contains(name) {
156        return Ok(());
157    }
158    if !visiting.insert(name.to_string()) {
159        return Err(LifecycleError::DependencyCycle);
160    }
161    let entry = services
162        .get(name)
163        .ok_or_else(|| LifecycleError::MissingDependency(name.to_string()))?;
164    for dependency in &entry.dependencies {
165        visit(dependency, services, visiting, visited, result)?;
166    }
167    visiting.remove(name);
168    visited.insert(name.to_string());
169    result.push(name.to_string());
170    Ok(())
171}
172
173#[cfg(test)]
174mod tests {
175    use super::*;
176
177    #[tokio::test]
178    async fn orders_shutdown_after_dependencies_and_cancels_token() {
179        let registry = ServiceRegistry::new();
180        registry.register("db", &[]).unwrap();
181        registry.register("api", &["db"]).unwrap();
182        registry.start("db").unwrap();
183        registry.start("api").unwrap();
184        let token = registry.token();
185        token.cancel();
186        let report = registry.shutdown(Duration::from_secs(1)).unwrap();
187        assert_eq!(report.order, vec!["api", "db"]);
188        assert_eq!(registry.state("api"), Some(ServiceState::Stopped));
189    }
190
191    #[test]
192    fn rejects_missing_dependencies_and_duplicate_services() {
193        let registry = ServiceRegistry::new();
194        assert_eq!(
195            registry.register("api", &["db"]),
196            Err(LifecycleError::MissingDependency("db".into()))
197        );
198        registry.register("db", &[]).unwrap();
199        assert_eq!(
200            registry.register("db", &[]),
201            Err(LifecycleError::DuplicateService)
202        );
203    }
204
205    #[test]
206    fn reports_zero_timeout_as_timed_out_and_detects_cycles() {
207        let registry = ServiceRegistry::new();
208        registry.register("one", &[]).unwrap();
209        let report = registry.shutdown(Duration::ZERO).unwrap();
210        assert_eq!(report.timed_out, vec!["one"]);
211    }
212}