Skip to main content

hyprstream_core/systemd/
signals.rs

1//! Unix signal handling for graceful shutdown and configuration reload
2//!
3//! Provides a signal coordinator that handles:
4//! - SIGTERM / SIGINT: Graceful shutdown
5//! - SIGHUP: Configuration reload
6//!
7//! # Architecture
8//!
9//! The coordinator uses broadcast channels to notify multiple listeners
10//! about signal events. This allows different parts of the application
11//! to respond to shutdown or reload requests independently.
12//!
13//! # Example
14//!
15//! ```ignore
16//! use hyprstream::systemd::SignalCoordinator;
17//!
18//! #[tokio::main]
19//! async fn main() {
20//!     let coordinator = SignalCoordinator::new();
21//!
22//!     // Get shutdown receiver before spawning
23//!     let mut shutdown_rx = coordinator.shutdown_receiver();
24//!
25//!     // Spawn signal handler
26//!     let signal_handle = tokio::spawn(async move {
27//!         coordinator.run().await;
28//!     });
29//!
30//!     // Your application logic here...
31//!
32//!     // Wait for shutdown signal
33//!     let _ = shutdown_rx.recv().await;
34//!     println!("Shutting down gracefully...");
35//! }
36//! ```
37
38use tokio::sync::broadcast;
39use tracing::{info, warn};
40
41/// Signal events that can be received
42#[derive(Debug, Clone, Copy, PartialEq, Eq)]
43pub enum SignalEvent {
44    /// Shutdown requested (SIGTERM, SIGINT)
45    Shutdown,
46    /// Configuration reload requested (SIGHUP)
47    Reload,
48}
49
50/// Coordinates Unix signal handling across the application
51///
52/// Creates broadcast channels for shutdown and reload events that multiple
53/// components can subscribe to.
54pub struct SignalCoordinator {
55    shutdown_tx: broadcast::Sender<()>,
56    reload_tx: broadcast::Sender<()>,
57}
58
59impl SignalCoordinator {
60    /// Create a new signal coordinator
61    ///
62    /// The coordinator doesn't start handling signals until `run()` is called.
63    pub fn new() -> Self {
64        let (shutdown_tx, _) = broadcast::channel(1);
65        let (reload_tx, _) = broadcast::channel(16); // More capacity for reload
66        Self {
67            shutdown_tx,
68            reload_tx,
69        }
70    }
71
72    /// Get a receiver for shutdown events
73    ///
74    /// Multiple receivers can be created. Each will receive the shutdown signal.
75    pub fn shutdown_receiver(&self) -> broadcast::Receiver<()> {
76        self.shutdown_tx.subscribe()
77    }
78
79    /// Get a receiver for reload events
80    ///
81    /// Multiple receivers can be created. Each will receive reload signals.
82    pub fn reload_receiver(&self) -> broadcast::Receiver<()> {
83        self.reload_tx.subscribe()
84    }
85
86    /// Signal shutdown to all listeners
87    ///
88    /// This can be called programmatically to trigger shutdown.
89    pub fn signal_shutdown(&self) {
90        let _ = self.shutdown_tx.send(());
91    }
92
93    /// Signal reload to all listeners
94    ///
95    /// This can be called programmatically to trigger config reload.
96    pub fn signal_reload(&self) {
97        let _ = self.reload_tx.send(());
98    }
99
100    /// Check if any shutdown receivers are active
101    pub fn has_shutdown_receivers(&self) -> bool {
102        self.shutdown_tx.receiver_count() > 0
103    }
104
105    /// Check if any reload receivers are active
106    pub fn has_reload_receivers(&self) -> bool {
107        self.reload_tx.receiver_count() > 0
108    }
109
110    /// Run the signal handler
111    ///
112    /// This should be spawned as an async task. It will run until a shutdown
113    /// signal is received.
114    ///
115    /// # Signals Handled
116    ///
117    /// - **SIGTERM**: Initiates graceful shutdown
118    /// - **SIGINT**: Initiates graceful shutdown (Ctrl+C)
119    /// - **SIGHUP**: Triggers configuration reload
120    ///
121    /// # Example
122    ///
123    /// ```ignore
124    /// let coordinator = SignalCoordinator::new();
125    /// let mut shutdown_rx = coordinator.shutdown_receiver();
126    ///
127    /// tokio::spawn(async move {
128    ///     coordinator.run().await;
129    /// });
130    /// ```
131    #[cfg(unix)]
132    pub async fn run(self) {
133        use tokio::signal::unix::{signal, SignalKind};
134
135        let mut sigterm = match signal(SignalKind::terminate()) {
136            Ok(s) => s,
137            Err(e) => {
138                warn!("Failed to register SIGTERM handler: {}", e);
139                return;
140            }
141        };
142
143        let mut sigint = match signal(SignalKind::interrupt()) {
144            Ok(s) => s,
145            Err(e) => {
146                warn!("Failed to register SIGINT handler: {}", e);
147                return;
148            }
149        };
150
151        let mut sighup = match signal(SignalKind::hangup()) {
152            Ok(s) => s,
153            Err(e) => {
154                warn!("Failed to register SIGHUP handler: {}", e);
155                return;
156            }
157        };
158
159        info!("Signal coordinator started (SIGTERM, SIGINT, SIGHUP)");
160
161        loop {
162            tokio::select! {
163                _ = sigterm.recv() => {
164                    info!("Received SIGTERM, initiating graceful shutdown");
165                    let _ = self.shutdown_tx.send(());
166                    break;
167                }
168                _ = sigint.recv() => {
169                    info!("Received SIGINT, initiating graceful shutdown");
170                    let _ = self.shutdown_tx.send(());
171                    break;
172                }
173                _ = sighup.recv() => {
174                    info!("Received SIGHUP, triggering configuration reload");
175                    let _ = self.reload_tx.send(());
176                    // Don't break - continue handling signals after reload
177                }
178            }
179        }
180
181        info!("Signal coordinator stopped");
182    }
183
184    /// Fallback for non-Unix systems
185    #[cfg(not(unix))]
186    pub async fn run(self) {
187        use tokio::signal;
188
189        info!("Signal coordinator started (Ctrl+C only on this platform)");
190
191        // On non-Unix, only Ctrl+C is available
192        match signal::ctrl_c().await {
193            Ok(()) => {
194                info!("Received Ctrl+C, initiating graceful shutdown");
195                let _ = self.shutdown_tx.send(());
196            }
197            Err(e) => {
198                warn!("Failed to listen for Ctrl+C: {}", e);
199            }
200        }
201
202        info!("Signal coordinator stopped");
203    }
204}
205
206impl Default for SignalCoordinator {
207    fn default() -> Self {
208        Self::new()
209    }
210}
211
212/// Create a simple shutdown future that completes on SIGTERM/SIGINT
213///
214/// This is a convenience function for simple use cases where you just
215/// need to wait for shutdown.
216///
217/// # Example
218///
219/// ```ignore
220/// // Start server with graceful shutdown
221/// axum::serve(listener, app)
222///     .with_graceful_shutdown(shutdown_signal())
223///     .await?;
224/// ```
225#[cfg(unix)]
226pub async fn shutdown_signal() {
227    use tokio::signal::unix::{signal, SignalKind};
228
229    let sigterm = signal(SignalKind::terminate());
230    let sigint = signal(SignalKind::interrupt());
231
232    match (sigterm, sigint) {
233        (Ok(mut sigterm), Ok(mut sigint)) => {
234            tokio::select! {
235                _ = sigterm.recv() => {
236                    info!("Received SIGTERM");
237                }
238                _ = sigint.recv() => {
239                    info!("Received SIGINT");
240                }
241            }
242        }
243        (Err(e), _) => {
244            tracing::error!("Failed to register SIGTERM: {}, falling back to ctrl_c", e);
245            if let Err(e) = tokio::signal::ctrl_c().await {
246                tracing::error!("Failed to listen for Ctrl+C: {}", e);
247            } else {
248                info!("Received Ctrl+C");
249            }
250        }
251        (_, Err(e)) => {
252            tracing::error!("Failed to register SIGINT: {}, falling back to ctrl_c", e);
253            if let Err(e) = tokio::signal::ctrl_c().await {
254                tracing::error!("Failed to listen for Ctrl+C: {}", e);
255            } else {
256                info!("Received Ctrl+C");
257            }
258        }
259    }
260}
261
262/// Fallback for non-Unix systems
263#[cfg(not(unix))]
264pub async fn shutdown_signal() {
265    if let Err(e) = tokio::signal::ctrl_c().await {
266        tracing::error!("Failed to listen for Ctrl+C: {}", e);
267    } else {
268        info!("Received Ctrl+C");
269    }
270}
271
272#[cfg(test)]
273mod tests {
274    use super::*;
275
276    #[test]
277    fn test_coordinator_creation() {
278        let coordinator = SignalCoordinator::new();
279        assert!(!coordinator.has_shutdown_receivers());
280        assert!(!coordinator.has_reload_receivers());
281    }
282
283    #[test]
284    fn test_receiver_subscription() {
285        let coordinator = SignalCoordinator::new();
286
287        let _shutdown_rx = coordinator.shutdown_receiver();
288        assert!(coordinator.has_shutdown_receivers());
289
290        let _reload_rx = coordinator.reload_receiver();
291        assert!(coordinator.has_reload_receivers());
292    }
293
294    #[test]
295    fn test_multiple_receivers() {
296        let coordinator = SignalCoordinator::new();
297
298        let _rx1 = coordinator.shutdown_receiver();
299        let _rx2 = coordinator.shutdown_receiver();
300        let _rx3 = coordinator.shutdown_receiver();
301
302        // All three should be active
303        assert!(coordinator.has_shutdown_receivers());
304    }
305
306    #[tokio::test]
307    async fn test_programmatic_shutdown() {
308        let coordinator = SignalCoordinator::new();
309        let mut rx = coordinator.shutdown_receiver();
310
311        // Signal shutdown
312        coordinator.signal_shutdown();
313
314        // Receiver should get the signal
315        let result = rx.recv().await;
316        assert!(result.is_ok());
317    }
318
319    #[tokio::test]
320    async fn test_programmatic_reload() {
321        let coordinator = SignalCoordinator::new();
322        let mut rx = coordinator.reload_receiver();
323
324        // Signal reload
325        coordinator.signal_reload();
326
327        // Receiver should get the signal
328        let result = rx.recv().await;
329        assert!(result.is_ok());
330    }
331
332    #[test]
333    fn test_signal_event_enum() {
334        assert_eq!(SignalEvent::Shutdown, SignalEvent::Shutdown);
335        assert_ne!(SignalEvent::Shutdown, SignalEvent::Reload);
336    }
337
338    #[test]
339    fn test_default_impl() {
340        let coordinator = SignalCoordinator::default();
341        assert!(!coordinator.has_shutdown_receivers());
342    }
343}