signstar_common/
traits.rs

1//! Common traits for signstar related crates.
2
3/// An interface for simple checks against a Signstar backend.
4///
5/// Backends may or may not be connected to a given Signstar host.
6/// This interface helps to establish whether they should be considered when evaluating state, or
7/// not.
8///
9/// # Note
10///
11/// Evaluating the availability and state of an HSM backend maybe subject to transient issues (e.g.
12/// network outage, USB connectivity).
13/// This is important to keep in mind when relying on [`BackendCheck::is_available`] and
14/// [`BackendCheck::is_provisioned`] in your code!
15pub trait BackendCheck {
16    /// Checks whether a Signstar backend connection is available on the current host.
17    ///
18    /// This function is meant as a simple check as to whether a backend is available to the
19    /// Signstar host executing this function, or not.
20    ///
21    /// It is not meant to track specific errors as to why a connection cannot be established.
22    /// However, implementations are advised to emit meaningful warning and error messages, if a
23    /// specific failure is encountered with a backend.
24    ///
25    /// # Note
26    ///
27    /// Implementations should only return `true`, if they are able to establish connection from
28    /// the current Signstar host.
29    /// Establishing a connection should ideally happen using unauthenticated functionality of the
30    /// backend.
31    /// Calling this function should answer the question "Is the backend connected to this host?".
32    ///
33    /// # Examples
34    ///
35    /// ```
36    /// use signstar_common::traits::BackendCheck;
37    ///
38    /// // A dummy backend, that doesn't do anything.
39    /// struct DummyBackend;
40    ///
41    /// impl BackendCheck for DummyBackend {
42    ///     /// This backend is always available.
43    ///     fn is_available(&self) -> bool {
44    ///         true
45    ///     }
46    ///
47    ///     /// This backend is always considered provisioned.
48    ///     fn is_provisioned(&self) -> bool {
49    ///         true
50    ///     }
51    /// }
52    ///
53    /// # fn main() -> testresult::TestResult {
54    /// let backend = DummyBackend;
55    /// assert!(backend.is_available());
56    /// # Ok(())
57    /// # }
58    /// ```
59    fn is_available(&self) -> bool;
60
61    /// Checks whether a Signstar backend has been provisioned.
62    ///
63    /// This function is meant as a simple check as to whether a backend is still using factory
64    /// settings, or not.
65    ///
66    /// It is not meant to track specific errors as to why a connection cannot be established, etc.
67    /// However, implementations are advised to emit meaningful warning and error messages, if a
68    /// specific failure is encountered with a backend.
69    ///
70    /// # Note
71    ///
72    /// Implementations should only return `true`, if they can ensure, that the backend has been
73    /// altered from its factory settings (indicators for this may differ depending on backend).
74    /// Calling this function should answer the question "Is the backend connected to this host and
75    /// is it provisioned?".
76    ///
77    /// # Examples
78    ///
79    /// ```
80    /// use signstar_common::traits::BackendCheck;
81    ///
82    /// // A dummy backend, that doesn't do anything.
83    /// struct DummyBackend;
84    ///
85    /// impl BackendCheck for DummyBackend {
86    ///     /// This backend is always available.
87    ///     fn is_available(&self) -> bool {
88    ///         true
89    ///     }
90    ///
91    ///     /// This backend is always considered provisioned.
92    ///     fn is_provisioned(&self) -> bool {
93    ///         true
94    ///     }
95    /// }
96    ///
97    /// # fn main() -> testresult::TestResult {
98    /// let backend = DummyBackend;
99    /// assert!(backend.is_provisioned());
100    /// # Ok(())
101    /// # }
102    /// ```
103    fn is_provisioned(&self) -> bool;
104}
105
106#[cfg(test)]
107mod tests {
108    use super::*;
109
110    struct DummyBackend;
111
112    impl BackendCheck for DummyBackend {
113        fn is_available(&self) -> bool {
114            true
115        }
116
117        fn is_provisioned(&self) -> bool {
118            true
119        }
120    }
121
122    /// Ensures, that [`BackendCheck::is_available`] works for a simple implementation.
123    #[test]
124    fn backend_check_is_available() {
125        let backend = DummyBackend;
126        assert!(backend.is_available());
127    }
128
129    /// Ensures, that [`BackendCheck::uses_default_credentials`] works for a simple
130    /// implementation.
131    #[test]
132    fn backend_check_uses_default_credentials() {
133        let backend = DummyBackend;
134        assert!(backend.is_provisioned());
135    }
136}
signstar_common/traits.rs

signstar_common/
traits.rs
