use std::io::{self, Write}; use clap_verbosity_flag::{LogLevel, Verbosity, VerbosityFilter}; use log::Level; use crate::{ error::ServerTlsErrorKind, log_format::{LogFormat, write_json_record}, }; pub mod args; pub trait Args { #[cfg(not(target_os = "macos"))] fn fix_openssl(&self) -> bool; fn ignore_tls_errors(&self) -> bool; /// How this program renders its logs. /// /// Required rather than defaulted: a default would let an implementor drop /// the override and silently report failures as prose to a caller that asked /// for JSON, with nothing — not even a warning — to catch it. fn log_format(&self) -> LogFormat; } /// Suggestions for re-running the command, for failures that have a known /// workaround. Empty when there is nothing useful to say — including when the /// relevant option is already in use. fn retry_hints(err: &anyhow::Error, args: &impl Args) -> Vec { let Some(kind) = ServerTlsErrorKind::from_error(err) else { return Vec::new(); }; let command_line = || { let argv = std::env::args().collect::>(); let program = argv.first().cloned().unwrap_or_default(); let rest = argv.get(1..).map(|rest| rest.join(" ")).unwrap_or_default(); (program, rest) }; // The blank line between the sentence and the command is part of the output // users already see; keep it exactly. let mut hints = Vec::new(); #[cfg(not(target_os = "macos"))] if kind == ServerTlsErrorKind::LegacyRenegotiation && !args.fix_openssl() { let (program, rest) = command_line(); hints.push(format!( "Re-run it with the `--fix-openssl` option to work around this issue, e.g.:\n\n{program} --fix-openssl {rest}" )); } if kind == ServerTlsErrorKind::Certificate && !args.ignore_tls_errors() { let (program, rest) = command_line(); hints.push(format!( "Re-run it with the `--ignore-tls-errors` option to ignore the certificate error, e.g.:\n\n{program} --ignore-tls-errors {rest}" )); } hints } /// Write one message to `w` the way `format` asks for. /// /// Text is emitted exactly as it always was, so existing output does not move. /// JSON is written directly rather than through the `log` macros, because these /// are reports rather than log lines: they must survive `--quiet`, which would /// otherwise discard the only explanation of a failed run. /// /// The record is rendered into one buffer and written once. `serde_json`'s /// `Display` would otherwise reach the stream in dozens of fragments, and any /// process sharing this stderr — the spawned authenticator, a connect script — /// could land a line inside a half-written record. fn write_message(w: &mut W, format: LogFormat, level: Level, message: &str) -> io::Result<()> { match format { LogFormat::Text => writeln!(w, "{message}"), LogFormat::Json => { // Callers pass the exact text line, blank-line padding included, so the // text form does not move. A record carries its own separation. let message = message.trim_start_matches('\n'); let mut line = Vec::new(); write_json_record( &mut line, &log::Record::builder() .level(level) .target(module_path!()) .args(format_args!("{message}")) .build(), )?; w.write_all(&line) } } } /// Report a user-facing line that is not a log record — a note, a warning, or /// advice about what to try next. /// /// Callers used `eprintln!` directly, which in JSON mode drops prose into a /// stream the caller is parsing a line at a time. Routing them here keeps one /// answer to "how does this program emit a user-facing line", and leaves the /// text form byte-for-byte unchanged. pub fn report(format: LogFormat, level: Level, message: &str) { let _ = write_message(&mut io::stderr().lock(), format, level, message); } fn write_failure(w: &mut W, format: LogFormat, err: &anyhow::Error, hints: &[String]) -> io::Result<()> { match format { LogFormat::Text => { writeln!(w, "\nError: {err:?}")?; for hint in hints { writeln!(w, "\n{hint}\n")?; } } LogFormat::Json => { write_message(w, format, Level::Error, &format!("{err:?}"))?; for hint in hints { write_message(w, format, Level::Error, hint)?; } } } Ok(()) } fn handle_error_to(w: &mut W, err: anyhow::Error, args: &impl Args) -> io::Result<()> { let hints = retry_hints(&err, args); write_failure(w, args.log_format(), &err, &hints) } pub fn handle_error(err: anyhow::Error, args: &impl Args) { // Nothing useful to do if stderr itself is gone. let _ = handle_error_to(&mut io::stderr().lock(), err, args); } #[derive(Debug)] pub struct InfoLevel; pub type InfoLevelVerbosity = Verbosity; impl LogLevel for InfoLevel { fn default_filter() -> VerbosityFilter { VerbosityFilter::Info } fn verbose_help() -> Option<&'static str> { Some("Enable verbose output, -v for debug, -vv for trace") } fn quiet_help() -> Option<&'static str> { Some("Decrease logging verbosity, -q for warnings, -qq for errors") } } pub trait ToVerboseArg { fn to_verbose_arg(&self) -> Option<&'static str>; } /// Convert the verbosity to the CLI argument value /// The default verbosity is `Info`, which means no argument is needed impl ToVerboseArg for InfoLevelVerbosity { fn to_verbose_arg(&self) -> Option<&'static str> { match self.filter() { VerbosityFilter::Off => Some("-qqq"), VerbosityFilter::Error => Some("-qq"), VerbosityFilter::Warn => Some("-q"), VerbosityFilter::Info => None, VerbosityFilter::Debug => Some("-v"), VerbosityFilter::Trace => Some("-vv"), } } } impl ToVerboseArg for Level { fn to_verbose_arg(&self) -> Option<&'static str> { match self { Level::Error => Some("-qq"), Level::Warn => Some("-q"), Level::Info => None, Level::Debug => Some("-v"), Level::Trace => Some("-vv"), } } } #[cfg(test)] mod tests { use anyhow::anyhow; use super::*; use crate::error::ServerTlsError; fn certificate_error() -> ServerTlsError { ServerTlsError { server: "https://vpn.example.com".into(), kind: ServerTlsErrorKind::Certificate, } } #[derive(Default)] struct TestArgs { #[cfg(not(target_os = "macos"))] fix_openssl: bool, ignore_tls_errors: bool, log_format: LogFormat, } impl Args for TestArgs { #[cfg(not(target_os = "macos"))] fn fix_openssl(&self) -> bool { self.fix_openssl } fn ignore_tls_errors(&self) -> bool { self.ignore_tls_errors } fn log_format(&self) -> LogFormat { self.log_format } } /// The seam that matters: `handle_error` must ask the args which format to /// use. Testing the writer alone would leave a version that always reports as /// prose passing every test. #[test] fn handle_error_honours_the_requested_format() { let args = TestArgs { log_format: LogFormat::Json, ..Default::default() }; let mut out = Vec::new(); handle_error_to(&mut out, anyhow!(certificate_error()), &args).expect("writing to a Vec cannot fail"); let out = String::from_utf8(out).expect("output should be UTF-8"); for line in out.lines() { serde_json::from_str::(line).unwrap_or_else(|e| panic!("not JSON: {line:?} ({e})")); } assert!(!out.is_empty(), "the failure must be reported"); } #[test] fn a_tls_failure_suggests_ignoring_tls_errors() { let hints = retry_hints(&anyhow!(certificate_error()), &TestArgs::default()); assert_eq!(hints.len(), 1, "expected one hint, got {hints:?}"); assert!(hints[0].contains("--ignore-tls-errors"), "got {:?}", hints[0]); // The command sits on its own line after a blank one, as it always has. assert!( hints[0].contains("e.g.:\n\n"), "blank line before the command: {:?}", hints[0] ); } #[test] fn hints_distinguish_legacy_and_unknown_tls_and_respect_both_flags() { let legacy = ServerTlsError { server: "https://vpn.example.com".into(), kind: ServerTlsErrorKind::LegacyRenegotiation, }; let hints = retry_hints(&anyhow!(legacy.clone()), &TestArgs::default()); if cfg!(target_os = "macos") { assert!(hints.is_empty()); } else { assert_eq!(hints.len(), 1); assert!(hints[0].contains("--fix-openssl")); } let args = TestArgs { #[cfg(not(target_os = "macos"))] fix_openssl: true, ignore_tls_errors: true, ..Default::default() }; assert!(retry_hints(&anyhow!(legacy), &args).is_empty()); assert!(retry_hints(&anyhow!(certificate_error()), &args).is_empty()); let other = ServerTlsError { server: "https://vpn.example.com".into(), kind: ServerTlsErrorKind::Other, }; assert!(retry_hints(&anyhow!(other), &TestArgs::default()).is_empty()); } /// Suggesting an option the user already passed is noise, and in JSON mode it /// would be an extra record on every failed run. #[test] fn no_hint_when_the_option_is_already_in_use() { let args = TestArgs { ignore_tls_errors: true, ..Default::default() }; assert!(retry_hints(&anyhow!(certificate_error()), &args).is_empty()); } /// Most failures have no known workaround; inventing advice for them would /// mislead. #[test] fn no_hints_for_an_unrelated_error() { let hints = retry_hints(&anyhow!("something else went wrong"), &TestArgs::default()); assert!(hints.is_empty(), "got {hints:?}"); } fn failure_output(format: LogFormat) -> String { let hints = vec!["Re-run it with the `--ignore-tls-errors` option".to_string()]; let mut out = Vec::new(); write_failure(&mut out, format, &anyhow!(certificate_error()), &hints).expect("writing to a Vec cannot fail"); String::from_utf8(out).expect("output should be UTF-8") } /// The failure is the program's final report, so in JSON mode it must be one /// more record on the same stream — and it must not be filtered away, which /// is why it does not go through the log macros. A run that fails silently is /// worse than one that fails noisily. #[test] fn the_failure_is_reported_as_records() { let out = failure_output(LogFormat::Json); let lines: Vec<_> = out.lines().collect(); assert_eq!(lines.len(), 2, "expected the error and its hint: {out:?}"); for line in lines { let v: serde_json::Value = serde_json::from_str(line).unwrap_or_else(|e| panic!("not JSON: {line:?} ({e})")); assert_eq!(v["level"], "ERROR"); } } /// The format has to be honoured, not merely available: reporting the failure /// as prose to a caller that asked for JSON is the defect this whole flag /// exists to remove. #[test] fn the_format_decides_how_the_failure_is_written() { assert!( serde_json::from_str::(failure_output(LogFormat::Json).lines().next().unwrap()).is_ok(), "json mode must not emit prose" ); let text = failure_output(LogFormat::Text); assert!(text.starts_with("\nError: "), "text mode keeps its shape: {text:?}"); assert!( serde_json::from_str::(text.trim()).is_err(), "text mode must not emit JSON: {text:?}" ); } }