uxum 0.9.5

Opinionated backend service framework based on axum
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

//! UNIX signal handling routines.

use thiserror::Error;
use tokio::signal::unix;
use tracing::{info, warn};

use crate::errors::IoError;

/// Signal handling error.
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum SignalError {
    /// Unable to register signal handler.
    #[error("Unable to register signal handler: {0}")]
    Register(IoError),
}

/// Register signal handler.
///
/// # Errors
///
/// Returns `Err` if internal call to [`unix::signal`] fails.
fn register(kind: unix::SignalKind) -> Result<unix::Signal, SignalError> {
    unix::signal(kind).map_err(|err| SignalError::Register(err.into()))
}

/// Unified listener for all handled signals.
pub struct SignalStream {
    /// Signal listener for SIGTERM.
    sig_term: unix::Signal,
    /// Signal listener for SIGINT.
    sig_int: unix::Signal,
    /// Signal listener for SIGQUIT.
    sig_quit: unix::Signal,
    /// Signal listener for SIGHUP.
    sig_hup: unix::Signal,
    /// Signal listener for SIGUSR1.
    sig_usr1: unix::Signal,
    /// Signal listener for SIGUSR2.
    sig_usr2: unix::Signal,
}

/// Signal type.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum Signal {
    /// SIGTERM.
    Terminate,
    /// SIGINT.
    Interrupt,
    /// SIGQUIT.
    Quit,
    /// SIGHUP.
    HangUp,
    /// SIGUSR1.
    UserDefined1,
    /// SIGUSR2.
    UserDefined2,
}

impl Signal {
    /// Name of a signal, as written in UNIX manual pages.
    #[must_use]
    pub fn name(&self) -> &'static str {
        match self {
            Self::Terminate => "SIGTERM",
            Self::Interrupt => "SIGINT",
            Self::Quit => "SIGQUIT",
            Self::HangUp => "SIGHUP",
            Self::UserDefined1 => "SIGUSR1",
            Self::UserDefined2 => "SIGUSR2",
        }
    }

    /// Whether a given signal should result in application shutting down.
    #[must_use]
    pub fn is_shutdown(&self) -> bool {
        matches!(self, Self::Terminate | Self::Interrupt | Self::Quit)
    }
}

impl SignalStream {
    /// Create new [`SignalStream`].
    ///
    /// Automatically registers all signal handlers.
    ///
    /// # Errors
    ///
    /// Returns `Err` if some signal handler failed to register.
    pub fn new() -> Result<Self, SignalError> {
        // TODO: cancellation token?
        let sig_term = register(unix::SignalKind::terminate())?;
        let sig_int = register(unix::SignalKind::interrupt())?;
        let sig_quit = register(unix::SignalKind::quit())?;
        let sig_hup = register(unix::SignalKind::hangup())?;
        let sig_usr1 = register(unix::SignalKind::user_defined1())?;
        let sig_usr2 = register(unix::SignalKind::user_defined2())?;

        Ok(Self {
            sig_term,
            sig_int,
            sig_quit,
            sig_hup,
            sig_usr1,
            sig_usr2,
        })
    }

    /// Wait for next received signal.
    ///
    /// # Errors
    ///
    /// Returns `Err` if some signal handler failed to register.
    pub async fn next(&mut self) -> Result<Signal, SignalError> {
        macro_rules! sig_recv {
            ($name:literal, $value:ident) => {
                info!(kind = $name, "received signal");
                return Ok(Signal::$value);
            };
        }
        macro_rules! sig_restart {
            ($name:literal, $sig:ident, $create:ident) => {
                warn!(kind = $name, "signal handler exited, restarting");
                self.$sig = register(unix::SignalKind::$create())?;
                continue;
            };
        }
        loop {
            tokio::select! {
                ret = self.sig_term.recv() => match ret {
                    Some(_) => { sig_recv!("SIGTERM", Terminate); }
                    None => { sig_restart!("SIGTERM", sig_term, terminate); }
                },
                ret = self.sig_int.recv() => match ret {
                    Some(_) => { sig_recv!("SIGINT", Interrupt); }
                    None => { sig_restart!("SIGINT", sig_int, interrupt); }
                },
                ret = self.sig_quit.recv() => match ret {
                    Some(_) => { sig_recv!("SIGQUIT", Quit); }
                    None => { sig_restart!("SIGQUIT", sig_quit, quit); }
                },
                ret = self.sig_hup.recv() => match ret {
                    Some(_) => { sig_recv!("SIGHUP", HangUp); }
                    None => { sig_restart!("SIGHUP", sig_hup, hangup); }
                },
                ret = self.sig_usr1.recv() => match ret {
                    Some(_) => { sig_recv!("SIGUSR1", UserDefined1); }
                    None => { sig_restart!("SIGUSR1", sig_usr1, user_defined1); }
                },
                ret = self.sig_usr2.recv() => match ret {
                    Some(_) => { sig_recv!("SIGUSR2", UserDefined2); }
                    None => { sig_restart!("SIGUSR2", sig_usr2, user_defined2); }
                },
            }
        }
    }
}