Mercurial > crates > nonstick

annotate src/logging.rs @ 174:9e4ce1631bd3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Dramatically expand documentation.
author Paul Fisher <paul@pfish.zone>
date Tue, 29 Jul 2025 18:58:27 -0400
parents e27c5c667a5a
children 5e4ea9650f87
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;
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 171
diff changeset
37 /// use nonstick::location;
159
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::logging::Level;
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:
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 171
diff changeset
48 /// pam_hdl.log(
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 171
diff changeset
49 /// Level::Warn,
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 171
diff changeset
50 /// location!(),
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 171
diff changeset
51 /// format_args!("this is unnecessarily verbose"),
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 171
diff changeset
52 /// );
159
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
53 /// # }
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 #[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
56 #[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
57 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
58 }
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
59
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
60 /// 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
61 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
62 /// 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
63 /// 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
64 ///
115
1e11a52b4665 Don't promise ordering for the log level.
Paul Fisher <paul@pfish.zone>
parents: 113
diff changeset
65 /// 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
66 /// depending upon the implementation.
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
67 #[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
68 pub enum Level {
155
ab8020566cd9 Only use real PAM constants for logging within `nonstick/libpam`.
Paul Fisher <paul@pfish.zone>
parents: 136
diff changeset
69 Error,
157
0099f2f79f86 Switch logging interface to accept fmt::Arguments.
Paul Fisher <paul@pfish.zone>
parents: 155
diff changeset
70 Warn,
155
ab8020566cd9 Only use real PAM constants for logging within `nonstick/libpam`.
Paul Fisher <paul@pfish.zone>
parents: 136
diff changeset
71 Info,
ab8020566cd9 Only use real PAM constants for logging within `nonstick/libpam`.
Paul Fisher <paul@pfish.zone>
parents: 136
diff changeset
72 Debug,
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
73 }
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
74
118
39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
75 /// 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
76 #[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
77 #[non_exhaustive]
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
78 pub struct Location<'a> {
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
79 pub file: &'a str,
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
80 pub line: u32,
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
81 pub function: &'a str,
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
82 }
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
83
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
84 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
85 /// 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
86 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
87 Self {
39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
88 file,
39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
89 line,
39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
90 function,
39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
91 }
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
92 }
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
93 }
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
94
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
95 /// The [`Location`] where this macro is inserted.
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
96 #[doc(hidden)]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
97 #[macro_export]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
98 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
99 () => {
39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
100 $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
101 };
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
102 }
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
103
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
104 /// 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
105 #[doc(hidden)]
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
106 #[macro_export]
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
107 macro_rules! __log_internal {
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
108 ($handle:expr, $level:ident, $($arg:tt)+) => {
157
0099f2f79f86 Switch logging interface to accept fmt::Arguments.
Paul Fisher <paul@pfish.zone>
parents: 155
diff changeset
109 $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
110 }
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
111 }
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
112
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
113 /// Ugly, hacky macro to get the current function name.
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
114 ///
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
115 /// [Stolen from Stack Overflow.][https://stackoverflow.com/a/40234666/39808]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
116 #[doc(hidden)]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
117 #[macro_export]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
118 macro_rules! __function {
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 fn p() {}
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
121 fn f<T>(_: T) -> &'static str {
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
122 ::std::any::type_name::<T>()
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
123 }
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
124 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
125 }};
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
126 }
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
127
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
128 /// 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
129 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
130 /// This supports `format!`-style formatting.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
131 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
132 /// # Example
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
133 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
134 /// ```no_run
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
135 /// # 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
136 /// # let load_error = "xxx";
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
137 /// nonstick::error!(
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
138 /// pam_handle,
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
139 /// "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
140 /// );
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
141 /// // 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
142 /// // at ERROR level on syslog.
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
143 /// # }
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
144 /// ```
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
145 #[macro_export]
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
146 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
147
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
148 /// 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
149 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
150 /// This supports `format!`-style formatting.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
151 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
152 /// # Example
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
153 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
154 /// ```no_run
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
155 /// # 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
156 /// # let (start, finish) = (0, 0);
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
157 /// nonstick::warn!(
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
158 /// pam_handle,
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
159 /// "loading took too long: {latency_ms} ms",
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
160 /// latency_ms = start - finish
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
161 /// );
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
162 /// // 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
163 /// // at WARN level on syslog.
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
164 /// # }
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
165 /// ```
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
166 #[macro_export]
157
0099f2f79f86 Switch logging interface to accept fmt::Arguments.
Paul Fisher <paul@pfish.zone>
parents: 155
diff changeset
167 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
168
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
169 /// 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
170 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
171 /// This supports `format!`-style formatting.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
172 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
173 /// # Example
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
174 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
175 /// ```no_run
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
176 /// # 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
177 /// 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
178 /// // 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
179 /// // at INFO level on syslog.
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
180 /// # }
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
181 /// ```
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
182 #[macro_export]
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
183 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
184
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
185 /// 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
186 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
187 /// 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
188 /// This supports `format!`-style formatting.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
189 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
190 /// # Example
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
191 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
192 /// ```no_run
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
193 /// # 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
194 /// # let userinfo_url = "https://zombo.com/";
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
195 /// 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
196 /// // 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
197 /// // "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
198 /// // at DEBUG level on syslog.
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
199 /// # }
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
200 /// ```
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
201 #[macro_export]
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
202 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
203
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
204 #[cfg(test)]
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
205 mod tests {
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
206 use super::*;
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
207 use std::cell::RefCell;
157
0099f2f79f86 Switch logging interface to accept fmt::Arguments.
Paul Fisher <paul@pfish.zone>
parents: 155
diff changeset
208 use std::fmt;
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
209
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
210 #[test]
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
211 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
212 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
213
159
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
214 impl Logger for TestLog {
157
0099f2f79f86 Switch logging interface to accept fmt::Arguments.
Paul Fisher <paul@pfish.zone>
parents: 155
diff changeset
215 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
216 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
217 }
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
218 }
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
219
159
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
220 let logger = TestLog(Default::default());
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
221
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
222 let something = Level::Error;
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
223 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
224 warn!(logger, "watch out!");
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
225 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
226 debug!(logger, "here is something: {something:?}");
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
227
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
228 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
229
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
230 assert_eq!(
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
231 vec![
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
232 (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
233 (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
234 (Level::Info, "here is some info: information".to_owned()),
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 115
diff changeset
235 (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
236 ],
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
237 logged
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
238 );
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
239 }
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
240 }