Skip to main content

appstruct_runtime/
supervisor.rs

1use crate::{ServiceHandle, ShutdownError};
2use async_trait::async_trait;
3use std::{
4    future::Future,
5    sync::{
6        Arc,
7        atomic::{AtomicU8, Ordering},
8    },
9};
10use tokio::{
11    sync::watch,
12    task::{JoinError, JoinHandle},
13};
14
15const RUNNING: u8 = 0;
16const SHUTTING_DOWN: u8 = 1;
17const EXITED: u8 = 2;
18
19#[derive(Clone, Copy, Debug, PartialEq, Eq)]
20pub enum BackgroundTaskExitKind {
21    Completed,
22    Failed,
23    Panicked,
24}
25
26#[derive(Clone, Debug, PartialEq, Eq)]
27pub struct BackgroundTaskExit {
28    pub service: &'static str,
29    pub kind: BackgroundTaskExitKind,
30    pub message: Option<String>,
31}
32
33pub trait BackgroundTaskObserver: Send + Sync {
34    fn exited(&self, event: &BackgroundTaskExit);
35}
36
37pub struct SupervisedTaskHandle {
38    service: &'static str,
39    shutdown: watch::Sender<bool>,
40    task: JoinHandle<Result<(), ShutdownError>>,
41    state: Arc<AtomicU8>,
42}
43
44impl SupervisedTaskHandle {
45    #[must_use]
46    pub fn spawn<F, Fut, O>(service: &'static str, observer: O, run: F) -> Self
47    where
48        F: FnOnce(watch::Receiver<bool>) -> Fut + Send + 'static,
49        Fut: Future<Output = Result<(), ShutdownError>> + Send + 'static,
50        O: BackgroundTaskObserver + 'static,
51    {
52        let (shutdown, receiver) = watch::channel(false);
53        let state = Arc::new(AtomicU8::new(RUNNING));
54        let task_state = Arc::clone(&state);
55        let task = tokio::spawn(async move {
56            let outcome = task_outcome(tokio::spawn(run(receiver)).await);
57            if task_state
58                .compare_exchange(RUNNING, EXITED, Ordering::AcqRel, Ordering::Acquire)
59                .is_ok()
60            {
61                let event = BackgroundTaskExit {
62                    service,
63                    kind: outcome.kind,
64                    message: outcome.message,
65                };
66                let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
67                    observer.exited(&event);
68                }));
69            }
70            outcome.result
71        });
72        Self {
73            service,
74            shutdown,
75            task,
76            state,
77        }
78    }
79
80    /// Request shutdown and wait for the supervised task to finish.
81    ///
82    /// # Errors
83    ///
84    /// Returns an error when the task reports a failure, panics, or cannot be joined.
85    pub async fn shutdown(self) -> Result<(), ShutdownError> {
86        let Self {
87            shutdown,
88            task,
89            state,
90            ..
91        } = self;
92        let _ = state.compare_exchange(RUNNING, SHUTTING_DOWN, Ordering::AcqRel, Ordering::Acquire);
93        let _ = shutdown.send(true);
94        task.await.map_err(ShutdownError::new)?
95    }
96}
97
98#[async_trait]
99impl ServiceHandle for SupervisedTaskHandle {
100    fn service(&self) -> &'static str {
101        self.service
102    }
103
104    async fn shutdown(self: Box<Self>) -> Result<(), ShutdownError> {
105        SupervisedTaskHandle::shutdown(*self).await
106    }
107}
108
109struct TaskOutcome {
110    result: Result<(), ShutdownError>,
111    kind: BackgroundTaskExitKind,
112    message: Option<String>,
113}
114
115fn task_outcome(result: Result<Result<(), ShutdownError>, JoinError>) -> TaskOutcome {
116    match result {
117        Ok(Ok(())) => TaskOutcome {
118            result: Ok(()),
119            kind: BackgroundTaskExitKind::Completed,
120            message: None,
121        },
122        Ok(Err(error)) => {
123            let message = error.to_string();
124            TaskOutcome {
125                result: Err(error),
126                kind: BackgroundTaskExitKind::Failed,
127                message: Some(message),
128            }
129        }
130        Err(error) => {
131            let kind = if error.is_panic() {
132                BackgroundTaskExitKind::Panicked
133            } else {
134                BackgroundTaskExitKind::Failed
135            };
136            let message = error.to_string();
137            TaskOutcome {
138                result: Err(ShutdownError::new(&message)),
139                kind,
140                message: Some(message),
141            }
142        }
143    }
144}
145
146#[cfg(test)]
147mod tests {
148    use super::{
149        BackgroundTaskExit, BackgroundTaskExitKind, BackgroundTaskObserver, SupervisedTaskHandle,
150    };
151    use crate::{ServiceHandle, ShutdownError};
152    use std::sync::{
153        Arc, Mutex,
154        atomic::{AtomicBool, Ordering},
155    };
156
157    #[derive(Clone, Default)]
158    struct RecordingObserver(Arc<Mutex<Vec<BackgroundTaskExit>>>);
159
160    impl BackgroundTaskObserver for RecordingObserver {
161        fn exited(&self, event: &BackgroundTaskExit) {
162            self.0.lock().unwrap().push(event.clone());
163        }
164    }
165
166    impl RecordingObserver {
167        async fn wait_for_exit(&self) -> BackgroundTaskExit {
168            tokio::time::timeout(std::time::Duration::from_secs(1), async {
169                loop {
170                    if let Some(event) = self.0.lock().unwrap().first().cloned() {
171                        return event;
172                    }
173                    tokio::task::yield_now().await;
174                }
175            })
176            .await
177            .unwrap()
178        }
179    }
180
181    #[tokio::test]
182    async fn observes_unexpected_completion() {
183        let observer = RecordingObserver::default();
184        let handle =
185            SupervisedTaskHandle::spawn("completed", observer.clone(), |_| async { Ok(()) });
186        let event = observer.wait_for_exit().await;
187        assert_eq!(event.kind, BackgroundTaskExitKind::Completed);
188        assert_eq!(event.service, "completed");
189        assert!(event.message.is_none());
190        handle.shutdown().await.unwrap();
191    }
192
193    #[tokio::test]
194    async fn observes_task_errors_and_returns_them_from_shutdown() {
195        let observer = RecordingObserver::default();
196        let handle = SupervisedTaskHandle::spawn("failed", observer.clone(), |_| async {
197            Err(ShutdownError::new("injected task error"))
198        });
199        let event = observer.wait_for_exit().await;
200        assert_eq!(event.kind, BackgroundTaskExitKind::Failed);
201        assert_eq!(event.message.as_deref(), Some("injected task error"));
202        assert_eq!(
203            Box::new(handle).shutdown().await.unwrap_err().to_string(),
204            "injected task error"
205        );
206    }
207
208    #[tokio::test]
209    async fn observes_panics_and_returns_them_from_shutdown() {
210        let observer = RecordingObserver::default();
211        let handle = SupervisedTaskHandle::spawn("panicked", observer.clone(), |_| async {
212            panic!("injected task panic");
213        });
214        let event = observer.wait_for_exit().await;
215        assert_eq!(event.kind, BackgroundTaskExitKind::Panicked);
216        assert!(event.message.unwrap().contains("injected task panic"));
217        assert!(handle.shutdown().await.is_err());
218    }
219
220    #[tokio::test]
221    async fn expected_shutdown_is_not_observed_as_an_exit() {
222        let observer = RecordingObserver::default();
223        let handle =
224            SupervisedTaskHandle::spawn("stopped", observer.clone(), |mut shutdown| async move {
225                shutdown.changed().await.map_err(ShutdownError::new)?;
226                Ok(())
227            });
228        handle.shutdown().await.unwrap();
229        assert!(observer.0.lock().unwrap().is_empty());
230    }
231
232    #[tokio::test]
233    async fn observer_panics_do_not_change_the_task_result() {
234        struct PanickingObserver(Arc<AtomicBool>);
235        impl BackgroundTaskObserver for PanickingObserver {
236            fn exited(&self, _: &BackgroundTaskExit) {
237                self.0.store(true, Ordering::Release);
238                panic!("injected observer panic");
239            }
240        }
241
242        let observed = Arc::new(AtomicBool::new(false));
243        let handle = SupervisedTaskHandle::spawn(
244            "observed",
245            PanickingObserver(Arc::clone(&observed)),
246            |_| async { Ok(()) },
247        );
248        tokio::time::timeout(std::time::Duration::from_secs(1), async {
249            while !observed.load(Ordering::Acquire) {
250                tokio::task::yield_now().await;
251            }
252        })
253        .await
254        .unwrap();
255        handle.shutdown().await.unwrap();
256    }
257}