Mercurial > crates > nonstick

annotate src/logging.rs @ 171:e27c5c667a5a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Create full new types for return code and flags, separate end to end. This plumbs the ReturnCode and RawFlags types through the places where we call into or are called from PAM. Also adds Sun documentation to the project.
author Paul Fisher <paul@pfish.zone>
date Fri, 25 Jul 2025 20:52:14 -0400
parents 634cd5f2ac8b
children 9e4ce1631bd3
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
1 //! PAM logging variables and macros.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
2 //!
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
3 //! PAM implementations usually include the ability to log to syslog in a way
171
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 159
diff changeset
4 //! that is associated with the log entry itself. This module defines
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 159
diff changeset
5 //! the interface we use for logging.
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
6 //!
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
7 //! We can't use [the `log` crate](https://docs.rs/log) because that requires
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
8 //! that any `Log` implementors be `Sync` and `Send`, and a PAM handle
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
9 //! may be neither. Furthermore, PAM handles are passed to PAM modules in
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
10 //! dynamic libraries, and `log` doesn't work across dynamic linking boundaries.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
11 //!
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
12 //! A `PamShared` implementation may still use the `log` crate on the backend,
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
13 //! and may even itself implement `log::Log`, but that interface is not exposed
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
14 //! to the generic PAM user.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
15
159
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
16 use crate::_doc::{man7, manbsd};
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
17 use std::fmt;
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
18
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
19 /// A trait for logging.
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
20 pub trait Logger {
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
21 /// Logs something via this PAM handle.
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
22 ///
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
23 /// You probably want to use one of the logging macros,
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
24 /// like [`error!`](crate::error!),
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
25 /// [`warn!`](crate::warn!),
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
26 /// [`info!`](crate::info!),
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
27 /// or [`debug!`](crate::debug!).
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
28 ///
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
29 /// In most PAM implementations, this will go to syslog.
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
30 /// See [Linux-PAM's `pam_syslog`][man7] or
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
31 /// [OpenPAM's `openpam_log`][manbsd] for more details.
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
32 ///
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
33 /// # Example
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
34 ///
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
35 /// ```no_run
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
36 /// # use nonstick::PamShared;
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
37 /// use nonstick::logging::Level;
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
38 /// use nonstick::location;
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
39 /// # fn _test(pam_hdl: impl PamShared) {
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
40 /// # let delay_ms = 100;
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
41 /// # let url = "https://zombo.com";
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
42 /// // Usually, instead of calling this manually, just use the macros.
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
43 /// nonstick::error!(pam_hdl, "something bad happened!");
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
44 /// nonstick::warn!(pam_hdl, "loading information took {delay_ms} ms");
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
45 /// nonstick::info!(pam_hdl, "using network backend");
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
46 /// nonstick::debug!(pam_hdl, "sending GET request to {url}");
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
47 /// // But if you really want to, you can call this yourself:
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
48 /// pam_hdl.log(Level::Warn, location!(), format_args!("this is unnecessarily verbose"));
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
49 /// # }
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
50 /// ```
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
51 #[doc = man7!(3 pam_syslog)]
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
52 #[doc = manbsd!(3 openpam_log)]
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
53 fn log(&self, level: Level, loc: Location<'_>, entry: fmt::Arguments);
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
54 }
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
55
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
56 /// An entry to be added to the log.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
57 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
58 /// The levels are in descending order of importance and correspond roughly
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
59 /// to the similarly-named levels in the `log` crate.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
60 ///
115
1e11a52b4665 Don't promise ordering for the log level.
Paul Fisher <paul@pfish.zone>
parents: 113
diff changeset
61 /// Their values are ordered monotonically, either increasing or decreasing,
1e11a52b4665 Don't promise ordering for the log level.
Paul Fisher <paul@pfish.zone>
parents: 113
diff changeset
62 /// depending upon the implementation.
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
63 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
64 pub enum Level {
155
ab8020566cd9 Only use real PAM constants for logging within `nonstick/libpam`.
Paul Fisher <paul@pfish.zone>
parents: 136
diff changeset
65 Error,
157
0099f2f79f86 Switch logging interface to accept fmt::Arguments.
Paul Fisher <paul@pfish.zone>
parents: 155
diff changeset
66 Warn,
155
ab8020566cd9 Only use real PAM constants for logging within `nonstick/libpam`.
Paul Fisher <paul@pfish.zone>
parents: 136
diff changeset
67 Info,
ab8020566cd9 Only use real PAM constants for logging within `nonstick/libpam`.
Paul Fisher <paul@pfish.zone>
parents: 136
diff changeset
68 Debug,
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
69 }
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
70
118
39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
71 /// The location of a log entry. Use [`location!`](crate::location!) to create this.
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
72 #[derive(Clone, Copy, Debug, Default)]
118
39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
73 #[non_exhaustive]
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
74 pub struct Location<'a> {
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
75 pub file: &'a str,
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
76 pub line: u32,
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
77 pub function: &'a str,
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
78 }
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
79
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
80 impl<'a> Location<'a> {
118
39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
81 /// Creates a new location. Just use [`location!`](crate::location!) instead.
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
82 pub fn new(file: &'a str, line: u32, function: &'a str) -> Self {
118
39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
83 Self {
39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
84 file,
39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
85 line,
39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
86 function,
39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
87 }
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
88 }
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
89 }
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
90
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
91 /// The [`Location`] where this macro is inserted.
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
92 #[doc(hidden)]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
93 #[macro_export]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
94 macro_rules! location {
118
39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
95 () => {
39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
96 $crate::logging::Location::new(file!(), line!(), $crate::__function!())
39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
97 };
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
98 }
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
99
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
100 /// Here's the guts of the logger thingy. You shouldn't be using this!
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
101 #[doc(hidden)]
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
102 #[macro_export]
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
103 macro_rules! __log_internal {
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
104 ($handle:expr, $level:ident, $($arg:tt)+) => {
157
0099f2f79f86 Switch logging interface to accept fmt::Arguments.
Paul Fisher <paul@pfish.zone>
parents: 155
diff changeset
105 $handle.log($crate::logging::Level::$level, $crate::location!(), format_args!($($arg)+));
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
106 }
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
107 }
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
108
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
109 /// Ugly, hacky macro to get the current function name.
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
110 ///
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
111 /// [Stolen from Stack Overflow.][https://stackoverflow.com/a/40234666/39808]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
112 #[doc(hidden)]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
113 #[macro_export]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
114 macro_rules! __function {
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
115 () => {{
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
116 fn p() {}
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
117 fn f<T>(_: T) -> &'static str {
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
118 ::std::any::type_name::<T>()
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
119 }
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
120 f(p).trim_end_matches("::p")
118
39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
121 }};
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
122 }
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
123
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
124 /// Logs a message at error level via the given PAM handle.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
125 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
126 /// This supports `format!`-style formatting.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
127 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
128 /// # Example
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
129 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
130 /// ```no_run
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
131 /// # fn _test(pam_handle: impl nonstick::PamShared) {
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
132 /// # let load_error = "xxx";
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
133 /// nonstick::error!(
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
134 /// pam_handle,
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
135 /// "error loading data from data source: {load_error}"
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
136 /// );
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
137 /// // Will log a message like "error loading data from data source: timed out"
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
138 /// // at ERROR level on syslog.
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
139 /// # }
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
140 /// ```
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
141 #[macro_export]
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
142 macro_rules! error { ($handle:expr, $($arg:tt)+) => { $crate::__log_internal!($handle, Error, $($arg)+);}}
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
143
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
144 /// Logs a message at warning level via the given PAM handle.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
145 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
146 /// This supports `format!`-style formatting.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
147 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
148 /// # Example
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
149 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
150 /// ```no_run
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
151 /// # fn _test(pam_handle: impl nonstick::PamShared) {
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
152 /// # let (start, finish) = (0, 0);
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
153 /// nonstick::warn!(
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
154 /// pam_handle,
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
155 /// "loading took too long: {latency_ms} ms",
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
156 /// latency_ms = start - finish
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
157 /// );
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
158 /// // Will log a message like "loading took too long: 495 ms"
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
159 /// // at WARN level on syslog.
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
160 /// # }
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
161 /// ```
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
162 #[macro_export]
157
0099f2f79f86 Switch logging interface to accept fmt::Arguments.
Paul Fisher <paul@pfish.zone>
parents: 155
diff changeset
163 macro_rules! warn { ($handle:expr, $($arg:tt)+) => { $crate::__log_internal!($handle, Warn, $($arg)+);}}
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
164
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
165 /// Logs a message at info level via the given PAM handle.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
166 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
167 /// This supports `format!`-style formatting.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
168 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
169 /// # Example
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
170 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
171 /// ```no_run
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
172 /// # fn _test(pam_handle: impl nonstick::PamShared) {
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
173 /// nonstick::info!(pam_handle, "using remote backend to load user data");
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
174 /// // Will log a message like "using remote backend to load user data"
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
175 /// // at INFO level on syslog.
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
176 /// # }
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
177 /// ```
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
178 #[macro_export]
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
179 macro_rules! info { ($handle:expr, $($arg:tt)+) => { $crate::__log_internal!($handle, Info, $($arg)+);}}
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
180
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
181 /// Logs a message at debug level via the given PAM handle.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
182 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
183 /// This level specially includes file/line/column information.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
184 /// This supports `format!`-style formatting.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
185 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
186 /// # Example
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
187 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
188 /// ```no_run
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
189 /// # fn _test(pam_handle: impl nonstick::PamShared) {
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
190 /// # let userinfo_url = "https://zombo.com/";
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
191 /// nonstick::debug!(pam_handle, "making HTTP GET request to {userinfo_url}");
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
192 /// // Will log a message like
134
6c1e1bdb4164 Use standard #[cfg] directives rather than custom proc macros.
Paul Fisher <paul@pfish.zone>
parents: 130
diff changeset
193 /// // "making HTTP GET request to https://zombo.com/"
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
194 /// // at DEBUG level on syslog.
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
195 /// # }
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
196 /// ```
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
197 #[macro_export]
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
198 macro_rules! debug { ($handle:expr, $($arg:tt)+) => { $crate::__log_internal!($handle, Debug, $($arg)+);}}
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
199
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
200 #[cfg(test)]
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
201 mod tests {
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
202 use super::*;
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
203 use std::cell::RefCell;
157
0099f2f79f86 Switch logging interface to accept fmt::Arguments.
Paul Fisher <paul@pfish.zone>
parents: 155
diff changeset
204 use std::fmt;
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
205
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
206 #[test]
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
207 fn test_logging() {
159
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
208 struct TestLog(RefCell<Vec<(Level, String)>>);
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
209
159
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
210 impl Logger for TestLog {
157
0099f2f79f86 Switch logging interface to accept fmt::Arguments.
Paul Fisher <paul@pfish.zone>
parents: 155
diff changeset
211 fn log(&self, level: Level, _: Location<'_>, text: fmt::Arguments) {
0099f2f79f86 Switch logging interface to accept fmt::Arguments.
Paul Fisher <paul@pfish.zone>
parents: 155
diff changeset
212 self.0.borrow_mut().push((level, text.to_string()))
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
213 }
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
214 }
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
215
159
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
216 let logger = TestLog(Default::default());
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
217
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
218 let something = Level::Error;
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
219 error!(logger, "here is another thing: {}", 99);
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
220 warn!(logger, "watch out!");
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
221 info!(logger, "here is some info: {info}", info = "information");
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
222 debug!(logger, "here is something: {something:?}");
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
223
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
224 let logged = logger.0.into_inner();
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
225
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
226 assert_eq!(
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
227 vec![
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
228 (Level::Error, "here is another thing: 99".to_owned()),
157
0099f2f79f86 Switch logging interface to accept fmt::Arguments.
Paul Fisher <paul@pfish.zone>
parents: 155
diff changeset
229 (Level::Warn, "watch out!".to_owned()),
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
230 (Level::Info, "here is some info: information".to_owned()),
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
231 (Level::Debug, "here is something: Error".to_owned()),
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
232 ],
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
233 logged
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
234 );
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
235 }
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
236 }