Skip to main content

rs_zero/core/
service_group.rs

1use std::{future::Future, sync::Arc, time::Duration};
2
3use tokio::task::JoinSet;
4
5use crate::core::{CoreError, CoreResult, FnService, Service, ShutdownToken, shutdown_signal};
6
7/// Service group runtime controls.
8#[derive(Debug, Clone, PartialEq, Eq)]
9pub struct ServiceGroupConfig {
10    /// Maximum time allowed for service stop hooks and task shutdown.
11    pub shutdown_timeout: Duration,
12    /// Whether the group cancels all services after the first service error.
13    pub stop_on_first_error: bool,
14}
15
16impl Default for ServiceGroupConfig {
17    fn default() -> Self {
18        Self {
19            shutdown_timeout: Duration::from_secs(30),
20            stop_on_first_error: true,
21        }
22    }
23}
24
25/// Handle that can request shutdown for a running [`ServiceGroup`].
26#[derive(Debug, Clone)]
27pub struct ServiceGroupHandle {
28    shutdown: ShutdownToken,
29}
30
31impl ServiceGroupHandle {
32    /// Requests group shutdown. Calling this method multiple times is safe.
33    pub fn stop(&self) {
34        self.shutdown.cancel();
35    }
36
37    /// Returns whether shutdown has been requested.
38    pub fn is_stopped(&self) -> bool {
39        self.shutdown.is_cancelled()
40    }
41}
42
43/// A group of async services that start together and stop together.
44///
45/// Services are started concurrently. Like go-zero's service group, startup
46/// order must not be relied on. When a process shutdown signal, explicit handle
47/// stop, or service error occurs, the group broadcasts a shutdown token, runs
48/// stop hooks, waits for tasks and returns aggregated errors if any.
49pub struct ServiceGroup {
50    config: ServiceGroupConfig,
51    services: Vec<Arc<dyn Service>>,
52    shutdown: ShutdownToken,
53}
54
55impl Default for ServiceGroup {
56    fn default() -> Self {
57        Self::new()
58    }
59}
60
61impl ServiceGroup {
62    /// Creates an empty service group with default controls.
63    pub fn new() -> Self {
64        Self::with_config(ServiceGroupConfig::default())
65    }
66
67    /// Creates an empty service group with custom controls.
68    pub fn with_config(config: ServiceGroupConfig) -> Self {
69        Self {
70            config,
71            services: Vec::new(),
72            shutdown: ShutdownToken::new(),
73        }
74    }
75
76    /// Adds a service to the group.
77    pub fn add<S>(&mut self, service: S) -> &mut Self
78    where
79        S: Service,
80    {
81        self.services.push(Arc::new(service));
82        self
83    }
84
85    /// Adds an already shared service to the group.
86    pub fn add_arc<S>(&mut self, service: Arc<S>) -> &mut Self
87    where
88        S: Service,
89    {
90        self.services.push(service);
91        self
92    }
93
94    /// Adds a service backed by an async start function.
95    pub fn add_fn<F, Fut>(&mut self, name: impl Into<String>, start: F) -> &mut Self
96    where
97        F: Fn(ShutdownToken) -> Fut + Send + Sync + 'static,
98        Fut: Future<Output = CoreResult<()>> + Send + 'static,
99    {
100        self.add(FnService::new(name, start))
101    }
102
103    /// Returns a handle that can stop the group while it is running.
104    pub fn handle(&self) -> ServiceGroupHandle {
105        ServiceGroupHandle {
106            shutdown: self.shutdown.clone(),
107        }
108    }
109
110    /// Starts all services and waits for Ctrl-C, Unix SIGTERM, or explicit stop.
111    pub async fn start(self) -> CoreResult<()> {
112        self.start_with_shutdown(shutdown_signal()).await
113    }
114
115    /// Starts all services and waits for the supplied shutdown future.
116    pub async fn start_with_shutdown<F>(self, shutdown: F) -> CoreResult<()>
117    where
118        F: Future<Output = ()> + Send,
119    {
120        if self.services.is_empty() {
121            return Ok(());
122        }
123
124        let mut tasks = spawn_services(&self.services, &self.shutdown);
125        let mut active = self.services.len();
126        let mut errors = Vec::new();
127        tokio::pin!(shutdown);
128
129        while active > 0 {
130            tokio::select! {
131                _ = &mut shutdown => {
132                    self.shutdown.cancel();
133                    break;
134                }
135                _ = self.shutdown.cancelled() => {
136                    break;
137                }
138                joined = tasks.join_next() => {
139                    let Some(joined) = joined else { break; };
140                    active -= 1;
141                    if handle_service_exit(joined, &mut errors) && self.config.stop_on_first_error {
142                        self.shutdown.cancel();
143                        break;
144                    }
145                }
146            }
147        }
148
149        if self.shutdown.is_cancelled() || active > 0 {
150            self.shutdown.cancel();
151            let deadline = tokio::time::Instant::now() + self.config.shutdown_timeout;
152            stop_services(
153                &self.services,
154                deadline,
155                self.config.shutdown_timeout,
156                &mut errors,
157            )
158            .await;
159            wait_for_tasks(
160                &mut tasks,
161                active,
162                deadline,
163                self.config.shutdown_timeout,
164                &mut errors,
165            )
166            .await;
167        }
168
169        into_group_result(errors)
170    }
171}
172
173struct ServiceTaskExit {
174    name: String,
175    result: CoreResult<()>,
176}
177
178fn spawn_services(
179    services: &[Arc<dyn Service>],
180    shutdown: &ShutdownToken,
181) -> JoinSet<ServiceTaskExit> {
182    let mut tasks = JoinSet::new();
183    for service in services {
184        let service = Arc::clone(service);
185        let token = shutdown.clone();
186        let name = service.name().to_string();
187        tasks.spawn(async move {
188            let result = service.start(token).await;
189            ServiceTaskExit { name, result }
190        });
191    }
192    tasks
193}
194
195fn handle_service_exit(
196    joined: Result<ServiceTaskExit, tokio::task::JoinError>,
197    errors: &mut Vec<String>,
198) -> bool {
199    match joined {
200        Ok(exit) => {
201            if let Err(error) = exit.result {
202                errors.push(format!("service {} failed: {error}", exit.name));
203                return true;
204            }
205        }
206        Err(error) => {
207            errors.push(format!("service task failed: {error}"));
208            return true;
209        }
210    }
211    false
212}
213
214async fn stop_services(
215    services: &[Arc<dyn Service>],
216    deadline: tokio::time::Instant,
217    timeout: Duration,
218    errors: &mut Vec<String>,
219) {
220    match tokio::time::timeout_at(deadline, run_stop_hooks(services)).await {
221        Ok(stop_errors) => errors.extend(stop_errors),
222        Err(_) => errors.push(format!(
223            "service group stop hooks timed out after {:?}",
224            timeout
225        )),
226    }
227}
228
229async fn run_stop_hooks(services: &[Arc<dyn Service>]) -> Vec<String> {
230    let mut tasks = JoinSet::new();
231    for service in services.iter().rev() {
232        let service = Arc::clone(service);
233        let name = service.name().to_string();
234        tasks.spawn(async move {
235            let result = service.stop().await;
236            (name, result)
237        });
238    }
239
240    let mut errors = Vec::new();
241    while let Some(joined) = tasks.join_next().await {
242        match joined {
243            Ok((_name, Ok(()))) => {}
244            Ok((name, Err(error))) => errors.push(format!("service {name} stop failed: {error}")),
245            Err(error) => errors.push(format!("service stop task failed: {error}")),
246        }
247    }
248    errors
249}
250
251async fn wait_for_tasks(
252    tasks: &mut JoinSet<ServiceTaskExit>,
253    active: usize,
254    deadline: tokio::time::Instant,
255    timeout: Duration,
256    errors: &mut Vec<String>,
257) {
258    let wait = async {
259        let mut remaining = active;
260        while remaining > 0 {
261            let Some(joined) = tasks.join_next().await else {
262                break;
263            };
264            remaining -= 1;
265            match joined {
266                Ok(exit) => {
267                    if let Err(error) = exit.result {
268                        errors.push(format!(
269                            "service {} failed during shutdown: {error}",
270                            exit.name
271                        ));
272                    }
273                }
274                Err(error) => errors.push(format!("service task failed during shutdown: {error}")),
275            }
276        }
277    };
278
279    if tokio::time::timeout_at(deadline, wait).await.is_err() {
280        tasks.abort_all();
281        errors.push(format!(
282            "service group shutdown timed out after {:?}",
283            timeout
284        ));
285    }
286}
287
288fn into_group_result(errors: Vec<String>) -> CoreResult<()> {
289    if errors.is_empty() {
290        Ok(())
291    } else {
292        Err(CoreError::Service(errors.join("; ")))
293    }
294}