diff --git a/README.md b/README.md index 721281e..9a50da2 100644 --- a/README.md +++ b/README.md @@ -55,13 +55,17 @@ Commands: connect Connect to a portal server disconnect Disconnect from the server launch-gui Launch the GUI + hip Generate HIP report help Print this message or the help of the given subcommand(s) Options: - --fix-openssl Get around the OpenSSL 'unsafe legacy renegotiation' error - --ignore-tls-errors Ignore TLS errors - -h, --help Print help - -V, --version Print version + --fix-openssl Uses extended compatibility mode for OpenSSL operations to support a broader range of systems and formats. + --ignore-tls-errors Ignore the TLS errors + --log-format Log output format. JSON is intended for non-interactive consumers; interactive prompts remain text. [default: text] [possible values: text, json] + -v, --verbose... Enable verbose output, -v for debug, -vv for trace + -q, --quiet... Decrease logging verbosity, -q for warnings, -qq for errors + -h, --help Print help (see more with '--help') + -V, --version Print version ``` > **Tip:** Use `gpclient help ` for detailed information on a specific command. diff --git a/apps/gpauth/src/cli.rs b/apps/gpauth/src/cli.rs index f84feae..8a39129 100644 --- a/apps/gpauth/src/cli.rs +++ b/apps/gpauth/src/cli.rs @@ -4,6 +4,7 @@ use gpapi::{ auth::{SamlAuthData, SamlAuthResult}, clap::{Args, InfoLevelVerbosity, args::Os, handle_error}, gp_params::GpParams, + log_format::{LogFormat, write_json_record}, os_profile::{ClientOs, OsProfile}, utils::{normalize_server, openssl}, }; @@ -76,6 +77,14 @@ struct Cli { #[arg(long, help = "Ignore TLS errors")] ignore_tls_errors: bool, + #[arg( + long, + value_enum, + default_value_t = LogFormat::Text, + help = "Log output format. JSON is intended for non-interactive consumers; interactive prompts remain text." + )] + log_format: LogFormat, + #[cfg(feature = "webview-auth")] #[arg(long, help = "Use the default browser for authentication")] default_browser: bool, @@ -108,6 +117,10 @@ impl Args for Cli { fn ignore_tls_errors(&self) -> bool { self.ignore_tls_errors } + + fn log_format(&self) -> LogFormat { + self.log_format + } } impl Cli { @@ -205,16 +218,23 @@ impl Cli { } } -fn init_logger(cli: &Cli) { - env_logger::builder() - .filter_level(cli.verbose.log_level_filter()) - .init(); +fn build_logger(cli: &Cli) -> env_logger::Builder { + let mut builder = env_logger::builder(); + builder.filter_level(cli.verbose.log_level_filter()); + + // Text is env_logger's own format, so leave it untouched rather than + // reimplementing it. + if cli.log_format == LogFormat::Json { + builder.format(write_json_record); + } + + builder } pub async fn run() { let cli = Cli::parse(); - init_logger(&cli); + build_logger(&cli).init(); info!("gpauth started: {}", VERSION); if let Err(err) = cli.run().await { @@ -240,8 +260,80 @@ pub fn print_auth_result(auth_result: anyhow::Result, host_id: Opt #[cfg(test)] mod tests { + use std::{ + io::Write, + sync::{Arc, Mutex}, + }; + + use log::Log; + use super::*; + /// gpauth's own result already goes to stdout as JSON; this makes its *logs* + /// readable the same way, so a caller driving it does not have to parse prose + /// on stderr to find out why an attempt failed. + #[test] + fn log_format_defaults_to_text() { + let cli = Cli::try_parse_from(["gpauth", "portal.example.com"]).expect("gpauth args should parse"); + + assert_eq!(cli.log_format, LogFormat::Text); + } + + #[test] + fn log_format_accepts_json() { + let cli = + Cli::try_parse_from(["gpauth", "portal.example.com", "--log-format", "json"]).expect("gpauth args should parse"); + + assert_eq!(cli.log_format, LogFormat::Json); + } + + /// A `Write` that keeps what was written, so the logger can be driven for + /// real instead of asserting on how it was configured. + #[derive(Clone, Default)] + struct Captured(Arc>>); + + impl Write for Captured { + fn write(&mut self, buf: &[u8]) -> std::io::Result { + self.0.lock().unwrap().extend_from_slice(buf); + Ok(buf.len()) + } + + fn flush(&mut self) -> std::io::Result<()> { + Ok(()) + } + } + + #[test] + fn json_format_emits_one_json_object_per_record() { + let cli = + Cli::try_parse_from(["gpauth", "portal.example.com", "--log-format", "json"]).expect("gpauth args should parse"); + + let captured = Captured::default(); + let logger = build_logger(&cli) + .target(env_logger::Target::Pipe(Box::new(captured.clone()))) + .build(); + + // Drive the logger directly: `init()` installs a global that a second test + // could not replace. + logger.log( + &log::Record::builder() + .level(log::Level::Info) + .target("gpauth") + .args(format_args!("authenticating against {}", "portal.example.com")) + .build(), + ); + logger.flush(); + + let out = String::from_utf8(captured.0.lock().unwrap().clone()).expect("log output should be UTF-8"); + let lines: Vec<_> = out.lines().collect(); + assert_eq!(lines.len(), 1, "expected exactly one line, got: {out:?}"); + + let v: serde_json::Value = serde_json::from_str(lines[0]).unwrap_or_else(|e| panic!("not JSON: {out:?} ({e})")); + assert_eq!(v["level"], "INFO"); + assert_eq!(v["target"], "gpauth"); + assert_eq!(v["message"], "authenticating against portal.example.com"); + } + #[test] fn os_defaults_to_runtime_os() { let cli = Cli::try_parse_from(["gpauth", "portal.example.com"]).expect("gpauth args should parse"); diff --git a/apps/gpclient/src/cli.rs b/apps/gpclient/src/cli.rs index ad44c09..1a31619 100644 --- a/apps/gpclient/src/cli.rs +++ b/apps/gpclient/src/cli.rs @@ -4,6 +4,7 @@ use anyhow::bail; use clap::{Parser, Subcommand}; use gpapi::{ clap::{Args, InfoLevelVerbosity, handle_error}, + log_format::{LogFormat, write_json_record}, utils::openssl, }; use log::info; @@ -32,6 +33,7 @@ pub(crate) struct SharedArgs<'a> { pub(crate) fix_openssl: bool, pub(crate) ignore_tls_errors: bool, pub(crate) verbose: &'a InfoLevelVerbosity, + pub(crate) log_format: LogFormat, } #[derive(Subcommand)] @@ -76,6 +78,14 @@ struct Cli { #[arg(long, help = "Ignore the TLS errors")] ignore_tls_errors: bool, + #[arg( + long, + value_enum, + default_value_t = LogFormat::Text, + help = "Log output format. JSON is intended for non-interactive consumers; interactive prompts remain text." + )] + log_format: LogFormat, + #[command(flatten)] verbose: InfoLevelVerbosity, } @@ -88,6 +98,10 @@ impl Args for Cli { fn ignore_tls_errors(&self) -> bool { self.ignore_tls_errors } + + fn log_format(&self) -> LogFormat { + self.log_format + } } impl Cli { @@ -132,6 +146,7 @@ impl Cli { fix_openssl: self.fix_openssl, ignore_tls_errors: self.ignore_tls_errors, verbose: &self.verbose, + log_format: self.log_format, }; if self.ignore_tls_errors { @@ -147,10 +162,16 @@ impl Cli { } } -fn init_logger(cli: &Cli) { +fn build_logger(cli: &Cli) -> env_logger::Builder { let mut builder = env_logger::builder(); builder.filter_level(cli.verbose.log_level_filter()); + // Text is env_logger's own format, so leave it untouched rather than + // reimplementing it. + if cli.log_format == LogFormat::Json { + builder.format(write_json_record); + } + // Output the log messages to a file if the command is the auth callback if let CliCommand::LaunchGui(args) = &cli.command { let auth_data = args.auth_data.as_deref().unwrap_or_default(); @@ -162,13 +183,13 @@ fn init_logger(cli: &Cli) { } } - builder.init(); + builder } pub(crate) async fn run() { let cli = Cli::parse(); - init_logger(&cli); + build_logger(&cli).init(); info!("gpclient started: {}", VERSION); @@ -177,3 +198,116 @@ pub(crate) async fn run() { std::process::exit(1); } } + +#[cfg(test)] +mod tests { + use std::{ + io::Write, + sync::{Arc, Mutex}, + }; + + use log::Log; + + use super::*; + + fn parse_cli(args: &[&str]) -> Cli { + Cli::try_parse_from(args).expect("arguments should parse") + } + + /// Text stays the default: a plain `gpclient connect` must keep the output it + /// has always had, or every existing user's terminal changes under them. + #[test] + fn log_format_defaults_to_text() { + assert_eq!(parse_cli(&["gpclient", "disconnect"]).log_format, LogFormat::Text); + } + + #[test] + fn log_format_accepts_json() { + assert_eq!( + parse_cli(&["gpclient", "--log-format", "json", "disconnect"]).log_format, + LogFormat::Json + ); + } + + /// An unknown value is a mistake worth reporting rather than silently + /// falling back to text, which would leave a caller parsing prose. + #[test] + fn log_format_rejects_an_unknown_value() { + // `.err()` rather than `unwrap_err()`: the Ok side is `Cli`, which is not + // `Debug`, and it is not worth deriving it just to print an error we expect. + let err = Cli::try_parse_from(["gpclient", "--log-format", "yaml", "disconnect"]) + .err() + .expect("an unknown log format should be rejected"); + let msg = err.to_string(); + assert!(msg.contains("yaml"), "error should name the input: {msg}"); + assert!(msg.contains("json"), "error should list the valid values: {msg}"); + } + + /// A `Write` that keeps what was written, so the logger can be driven for + /// real instead of asserting on how it was configured. + #[derive(Clone, Default)] + struct Captured(Arc>>); + + impl Captured { + fn contents(&self) -> String { + String::from_utf8(self.0.lock().unwrap().clone()).expect("log output should be UTF-8") + } + } + + impl Write for Captured { + fn write(&mut self, buf: &[u8]) -> std::io::Result { + self.0.lock().unwrap().extend_from_slice(buf); + Ok(buf.len()) + } + + fn flush(&mut self) -> std::io::Result<()> { + Ok(()) + } + } + + fn log_one_record(args: &[&str]) -> String { + let captured = Captured::default(); + let logger = build_logger(&parse_cli(args)) + .target(env_logger::Target::Pipe(Box::new(captured.clone()))) + .build(); + + // Drive the logger directly: `init()` installs a global that a second test + // could not replace. + logger.log( + &log::Record::builder() + .level(log::Level::Info) + .target("gpclient") + .args(format_args!("connected to {}", "vpn.example.com")) + .build(), + ); + logger.flush(); + + captured.contents() + } + + /// The point of the flag: with `json`, a caller gets fields, and gets them one + /// record per line so the stream can be read incrementally. + #[test] + fn json_format_emits_one_json_object_per_record() { + let out = log_one_record(&["gpclient", "--log-format", "json", "disconnect"]); + + let lines: Vec<_> = out.lines().collect(); + assert_eq!(lines.len(), 1, "expected exactly one line, got: {out:?}"); + + let v: serde_json::Value = serde_json::from_str(lines[0]).unwrap_or_else(|e| panic!("not JSON: {out:?} ({e})")); + assert_eq!(v["level"], "INFO"); + assert_eq!(v["target"], "gpclient"); + assert_eq!(v["message"], "connected to vpn.example.com"); + } + + #[test] + fn text_format_is_left_alone() { + let out = log_one_record(&["gpclient", "disconnect"]); + + assert!(out.contains("connected to vpn.example.com"), "message missing: {out:?}"); + assert!( + serde_json::from_str::(out.trim()).is_err(), + "text output should not be JSON: {out:?}" + ); + } +} diff --git a/apps/gpclient/src/connect/credential.rs b/apps/gpclient/src/connect/credential.rs index 52c8279..71444ef 100644 --- a/apps/gpclient/src/connect/credential.rs +++ b/apps/gpclient/src/connect/credential.rs @@ -85,6 +85,7 @@ impl ConnectHandler<'_> { .sslkey(self.args.sslkey.as_deref()) .key_password(key_password.as_deref()) .browser(browser) + .log_format(self.shared_args.log_format) .verbose(verbose); #[cfg(feature = "webview-auth")] diff --git a/apps/gpclient/src/connect/gateway.rs b/apps/gpclient/src/connect/gateway.rs index 3b29480..8963be1 100644 --- a/apps/gpclient/src/connect/gateway.rs +++ b/apps/gpclient/src/connect/gateway.rs @@ -7,6 +7,7 @@ use std::{ }; use gpapi::{ + clap::report, cookie_store, credential::{AuthCookieCredential, Credential}, gateway::{GatewayLogin, GatewayLoginContext, SessionExtensionAuth, gateway_login, gateway_login_with_context}, @@ -17,7 +18,7 @@ use gpapi::{ utils::shutdown_signal, }; use inquire::Text; -use log::{info, warn}; +use log::{Level, info, warn}; use openconnect::{Vpn, VpnBuilder}; use tokio::{runtime::Handle, task::JoinHandle}; @@ -281,9 +282,22 @@ impl ConnectHandler<'_> { return; } - eprintln!("\nNOTE: Gateway authentication failed after portal login."); - eprintln!("NOTE: If this server also accepts direct gateway login, try:"); - eprintln!("NOTE: {}", direct_gateway_command(gateway)); + let format = self.shared_args.log_format; + report( + format, + Level::Warn, + "\nNOTE: Gateway authentication failed after portal login.", + ); + report( + format, + Level::Warn, + "NOTE: If this server also accepts direct gateway login, try:", + ); + report( + format, + Level::Warn, + &format!("NOTE: {}", direct_gateway_command(gateway)), + ); } async fn login_gateway( @@ -384,6 +398,7 @@ impl ConnectHandler<'_> { vpn_clone.disconnect(); }); + let log_format = self.shared_args.log_format; let connect_result = vpn.connect(move |vpn_session_info| { tunnel_established_on_connect.store(true, Ordering::SeqCst); write_pid_file(); @@ -394,7 +409,7 @@ impl ConnectHandler<'_> { let session_info = session_info_from_vpn(vpn_session_info, allow_extend_session); info!("VPN session info: {}", session_info.log_summary()); - let task = spawn_session_runtime_with_info(&runtime_handle, session_ctx, session_info); + let task = spawn_session_runtime_with_info(&runtime_handle, session_ctx, session_info, log_format); session_task_on_connect.lock().unwrap().replace(task); }); let tunnel_established = tunnel_established.load(Ordering::SeqCst); diff --git a/apps/gpclient/src/connect/mod.rs b/apps/gpclient/src/connect/mod.rs index 39fc07d..cacef1e 100644 --- a/apps/gpclient/src/connect/mod.rs +++ b/apps/gpclient/src/connect/mod.rs @@ -6,6 +6,7 @@ use std::cell::RefCell; use anyhow::bail; use gpapi::{ + clap::report, error::PortalError, gateway::{GatewayLoginContext, GatewaySelection}, gp_params::GpParams, @@ -14,7 +15,7 @@ use gpapi::{ utils::request::RequestIdentityError, }; use inquire::{Password, PasswordDisplayMode, Select}; -use log::{info, warn}; +use log::{Level, info, warn}; use crate::cli::SharedArgs; @@ -110,8 +111,17 @@ impl<'a> ConnectHandler<'a> { match root_cause { RequestIdentityError::NoKey => { - eprintln!("ERROR: No private key found in the certificate file"); - eprintln!("ERROR: Please provide the private key file using the `-k` option"); + let format = self.shared_args.log_format; + report( + format, + Level::Error, + "ERROR: No private key found in the certificate file", + ); + report( + format, + Level::Error, + "ERROR: Please provide the private key file using the `-k` option", + ); return Ok(()); } RequestIdentityError::NoPassphrase(cert_type) | RequestIdentityError::DecryptError(cert_type) => { @@ -153,8 +163,17 @@ impl<'a> ConnectHandler<'a> { info!("Trying the gateway authentication workflow..."); self.connect_gateway_with_prelogin(server, server, false, None).await?; - eprintln!("\nNOTE: the server may be a gateway, not a portal."); - eprintln!("NOTE: try to use the `--as-gateway` option if you were authenticated twice."); + let format = self.shared_args.log_format; + report( + format, + Level::Warn, + "\nNOTE: the server may be a gateway, not a portal.", + ); + report( + format, + Level::Warn, + "NOTE: try to use the `--as-gateway` option if you were authenticated twice.", + ); Ok(()) } else { diff --git a/apps/gpclient/src/session.rs b/apps/gpclient/src/session.rs index d0ed18e..ce7eee8 100644 --- a/apps/gpclient/src/session.rs +++ b/apps/gpclient/src/session.rs @@ -1,11 +1,13 @@ use std::time::{Duration, SystemTime, UNIX_EPOCH}; use gpapi::{ + clap::report, gateway::{SessionContext, SessionExtensionAuth, extend_session}, + log_format::LogFormat, os_profile::OsProfile, session::{SessionInfo, SessionRequestArgs, SessionWarning}, }; -use log::{info, warn}; +use log::{Level, info, warn}; use openconnect::VpnSessionInfo; use tokio::{runtime::Handle, task::JoinHandle}; @@ -59,11 +61,12 @@ pub(crate) fn spawn_session_runtime_with_info( handle: &Handle, session_ctx: SessionContext, session_info: SessionInfo, + log_format: LogFormat, ) -> JoinHandle<()> { - handle.spawn(run_session_runtime(session_ctx, session_info)) + handle.spawn(run_session_runtime(session_ctx, session_info, log_format)) } -async fn run_session_runtime(session_ctx: SessionContext, mut session_info: SessionInfo) { +async fn run_session_runtime(session_ctx: SessionContext, mut session_info: SessionInfo, log_format: LogFormat) { loop { let Some(schedule) = build_session_warning_schedule(&session_info) else { info!("No session warning schedule provided by the gateway"); @@ -72,7 +75,7 @@ async fn run_session_runtime(session_ctx: SessionContext, mut session_info: Sess tokio::time::sleep(schedule.delay).await; - eprintln!("\nWARNING: {}", schedule.message); + report(log_format, Level::Warn, &format!("\nWARNING: {}", schedule.message)); if !schedule.should_auto_extend { info!("Session extension is not allowed by the gateway"); @@ -87,12 +90,16 @@ async fn run_session_runtime(session_ctx: SessionContext, mut session_info: Sess return; }; - eprintln!("Session extended."); + report(log_format, Level::Info, "Session extended."); session_info = next_session_info; } Err(err) => { warn!("Failed to extend session: {}", err); - eprintln!("WARNING: Failed to extend session: {}", err); + report( + log_format, + Level::Warn, + &format!("WARNING: Failed to extend session: {}", err), + ); return; } } diff --git a/crates/gpapi/src/clap/mod.rs b/crates/gpapi/src/clap/mod.rs index 62ca9e9..55c9c69 100644 --- a/crates/gpapi/src/clap/mod.rs +++ b/crates/gpapi/src/clap/mod.rs @@ -1,33 +1,139 @@ +use std::io::{self, Write}; + use clap_verbosity_flag::{LogLevel, Verbosity, VerbosityFilter}; use log::Level; -use crate::error::PortalError; +use crate::{ + error::PortalError, + log_format::{LogFormat, write_json_record}, +}; pub mod args; pub trait Args { 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; } -pub fn handle_error(err: anyhow::Error, args: &impl Args) { - eprintln!("\nError: {:?}", err); - +/// 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(err) = err.downcast_ref::() else { - return; + 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(); + if err.is_legacy_openssl_error() && !args.fix_openssl() { - eprintln!("\nRe-run it with the `--fix-openssl` option to work around this issue, e.g.:\n"); - let args = std::env::args().collect::>(); - eprintln!("{} --fix-openssl {}\n", args[0], args[1..].join(" ")); + 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 err.is_tls_error() && !args.ignore_tls_errors() { - eprintln!("\nRe-run it with the `--ignore-tls-errors` option to ignore the certificate error, e.g.:\n"); - let args = std::env::args().collect::>(); - eprintln!("{} --ignore-tls-errors {}\n", args[0], args[1..].join(" ")); + 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)] @@ -79,3 +185,129 @@ impl ToVerboseArg for Level { } } } + +#[cfg(test)] +mod tests { + use anyhow::anyhow; + + use super::*; + + #[derive(Default)] + struct TestArgs { + fix_openssl: bool, + ignore_tls_errors: bool, + log_format: LogFormat, + } + + impl Args for TestArgs { + 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!(PortalError::TlsError), &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!(PortalError::TlsError), &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] + ); + } + + /// 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!(PortalError::TlsError), &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!(PortalError::TlsError), &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:?}" + ); + } +} diff --git a/crates/gpapi/src/lib.rs b/crates/gpapi/src/lib.rs index c953202..c9462bc 100644 --- a/crates/gpapi/src/lib.rs +++ b/crates/gpapi/src/lib.rs @@ -4,6 +4,7 @@ pub mod credential; pub mod error; pub mod gateway; pub mod gp_params; +pub mod log_format; pub mod os_profile; pub mod params; pub mod portal; diff --git a/crates/gpapi/src/log_format.rs b/crates/gpapi/src/log_format.rs new file mode 100644 index 0000000..920aea5 --- /dev/null +++ b/crates/gpapi/src/log_format.rs @@ -0,0 +1,164 @@ +//! Machine-readable log output. +//! +//! The default human format is fine at a terminal, but tools that drive +//! gpclient headless have to parse it — and end up matching on prose, including +//! text that comes from dependencies rather than from this project. JSON lines +//! give those callers fields instead. +//! +//! This module deliberately depends only on `log` and `serde_json`, so every +//! binary can use it without pulling in a logging backend, and so the rendering +//! can be tested without installing a global logger. + +use std::io::{self, Write}; + +use chrono::{SecondsFormat, Utc}; +use serde_json::json; + +/// How log records are rendered. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +#[cfg_attr(feature = "clap", derive(clap::ValueEnum))] +pub enum LogFormat { + /// The human-readable default. + #[default] + Text, + /// One JSON object per line. + Json, +} + +impl LogFormat { + /// The name this format is known by on a command line. + pub fn as_str(&self) -> &'static str { + match self { + Self::Text => "text", + Self::Json => "json", + } + } +} + +/// Write a [`log::Record`] to `w` as one JSON line, newline included. +/// +/// This is the form a logging backend needs, and it writes into the buffer the +/// backend already handed us rather than allocating a line to be copied. It +/// takes a `Record` and a `Write` rather than any backend's own types, so `log` +/// stays the only logging dependency here — with `env_logger`, this function +/// *is* the format callback: +/// +/// ```ignore +/// // Not compiled as a doctest: env_logger is an optional dependency of this +/// // crate, so it is not linked when the docs are built. +/// env_logger::builder().format(write_json_record).init(); +/// ``` +pub fn write_json_record(w: &mut W, record: &log::Record) -> io::Result<()> { + writeln!( + w, + "{}", + json!({ + "timestamp": Utc::now().to_rfc3339_opts(SecondsFormat::Millis, true), + "level": record.level().as_str(), + "target": record.target(), + "message": record.args().to_string(), + }) + ) +} + +#[cfg(test)] +mod tests { + use chrono::{DateTime, SubsecRound}; + use log::Level; + + use super::*; + + fn parse(line: &str) -> serde_json::Value { + serde_json::from_str(line).expect("each line must be valid JSON") + } + + fn write_record(record: &log::Record) -> String { + let mut buf = Vec::new(); + write_json_record(&mut buf, record).expect("writing to a Vec cannot fail"); + String::from_utf8(buf).expect("output should be UTF-8") + } + + /// The fields a consumer is promised, taken off a `Record` as a backend + /// hands it over. + #[test] + fn record_renders_the_expected_fields() { + // Built inline: `format_args!` borrows its arguments for the statement it + // appears in, so a `Record` held in a `let` would outlive them. + let v = parse(&write_record( + &log::Record::builder() + .level(Level::Error) + .target("gpclient::connect") + .args(format_args!("portal {} unreachable", "vpn.example.com")) + .build(), + )); + + assert_eq!(v["level"], "ERROR"); + assert_eq!(v["target"], "gpclient::connect"); + assert_eq!(v["message"], "portal vpn.example.com unreachable"); + } + + /// Without a timestamp the JSON output would be strictly less informative + /// than the text format it replaces, and a consumer could not order or + /// correlate events. + #[test] + fn records_carry_a_utc_timestamp() { + let before = Utc::now(); + let v = parse(&write_record( + &log::Record::builder() + .level(Level::Info) + .target("t") + .args(format_args!("connected")) + .build(), + )); + let after = Utc::now(); + + let ts = v["timestamp"].as_str().expect("timestamp must be a string"); + let parsed = DateTime::parse_from_rfc3339(ts) + .unwrap_or_else(|e| panic!("timestamp must be RFC 3339: {ts:?} ({e})")) + .with_timezone(&Utc); + + assert!(ts.ends_with('Z'), "timestamp must be UTC, got {ts:?}"); + assert!( + parsed >= before.trunc_subsecs(3) && parsed <= after, + "timestamp {parsed} should be between {before} and {after}" + ); + } + + /// The backend appends records to one stream, so each has to terminate its + /// own line — exactly one, or the next record joins this one. A message + /// containing a newline must be escaped into the JSON string rather than + /// splitting the record in two. + #[test] + fn record_ends_with_a_single_newline() { + let out = write_record( + &log::Record::builder() + .level(Level::Info) + .target("t") + .args(format_args!("first\nsecond")) + .build(), + ); + + assert!(out.ends_with('\n'), "record must terminate its line: {out:?}"); + assert_eq!(out.matches('\n').count(), 1, "record must be one line: {out:?}"); + assert_eq!(parse(&out)["message"], "first\nsecond", "the newline must survive"); + } + + /// `as_str` is what gets passed to a child process on the command line, and + /// clap parses that with the names from its own `ValueEnum` derive. If the + /// two ever disagree, gpclient hands gpauth a value gpauth rejects. + #[cfg(feature = "clap")] + #[test] + fn as_str_agrees_with_the_names_clap_parses() { + use clap::ValueEnum; + + for format in [LogFormat::Text, LogFormat::Json] { + let clap_name = format + .to_possible_value() + .expect("every variant is selectable") + .get_name() + .to_owned(); + + assert_eq!(format.as_str(), clap_name); + } + } +} diff --git a/crates/gpapi/src/process/auth_launcher.rs b/crates/gpapi/src/process/auth_launcher.rs index 1d477a5..44c248a 100644 --- a/crates/gpapi/src/process/auth_launcher.rs +++ b/crates/gpapi/src/process/auth_launcher.rs @@ -1,10 +1,13 @@ -use std::{path::PathBuf, process::Stdio}; +use std::{ + path::{Path, PathBuf}, + process::Stdio, +}; use anyhow::bail; use common::binary_paths; use tokio::process::Command; -use crate::{auth::SamlAuthResult, credential::Credential, os_profile::OsProfile}; +use crate::{auth::SamlAuthResult, credential::Credential, log_format::LogFormat, os_profile::OsProfile}; use super::command_traits::CommandExt; @@ -29,6 +32,7 @@ pub struct SamlAuthLauncher<'a> { default_browser: bool, browser: Option<&'a str>, verbose: Option<&'a str>, + log_format: LogFormat, } impl<'a> SamlAuthLauncher<'a> { @@ -54,6 +58,7 @@ impl<'a> SamlAuthLauncher<'a> { default_browser: false, browser: None, verbose: None, + log_format: LogFormat::Text, } } @@ -127,18 +132,27 @@ impl<'a> SamlAuthLauncher<'a> { self } + /// Render the child's logs the same way as ours. + /// + /// gpauth inherits this process's stderr, so both processes must use the same + /// format to keep the stream consistent. + pub fn log_format(mut self, log_format: LogFormat) -> Self { + self.log_format = log_format; + self + } + pub fn verbose(mut self, verbose: Option<&'a str>) -> Self { self.verbose = verbose; self } - /// Launch the authenticator binary as the current user or SUDO_USER if available. - pub async fn launch(self) -> anyhow::Result { - let program = self - .auth_executable - .map(PathBuf::from) - .unwrap_or_else(binary_paths::gpauth); - let mut auth_cmd = Command::new(&program); + /// The command line this launcher will run. + /// + /// Split out from `launch` so a test can observe the argv the child actually + /// receives: asserting on the builder's own fields would not catch an + /// argument that never gets appended. + fn build_command(&self, program: &Path) -> Command { + let mut auth_cmd = Command::new(program); auth_cmd.arg(self.server); if self.gateway { @@ -200,10 +214,23 @@ impl<'a> SamlAuthLauncher<'a> { auth_cmd.arg("--browser").arg(browser); } + auth_cmd.arg("--log-format").arg(self.log_format.as_str()); + if let Some(verbose) = self.verbose { auth_cmd.arg(verbose); } + auth_cmd + } + + /// Launch the authenticator binary as the current user or SUDO_USER if available. + pub async fn launch(self) -> anyhow::Result { + let program = self + .auth_executable + .map(PathBuf::from) + .unwrap_or_else(binary_paths::gpauth); + let auth_cmd = self.build_command(&program); + let mut non_root_cmd = auth_cmd.into_non_root()?; let child = non_root_cmd.kill_on_drop(true).stdout(Stdio::piped()).spawn(); @@ -256,6 +283,45 @@ mod tests { assert_eq!(launcher.client_version, Some("6.0.0")); } + fn child_args(launcher: SamlAuthLauncher) -> Vec { + launcher + .build_command(Path::new("gpauth")) + .as_std() + .get_args() + .map(|arg| arg.to_string_lossy().into_owned()) + .collect() + } + + /// gpauth writes to the same stderr as its parent, so a caller reading the + /// parent's JSON would hit gpauth's text records mid-stream unless the format + /// is passed down. + #[test] + fn json_is_forwarded_to_the_child() { + let args = child_args(SamlAuthLauncher::new("portal.example.com").log_format(LogFormat::Json)); + + assert!( + args.windows(2).any(|pair| pair == ["--log-format", "json"]), + "expected --log-format json in {args:?}" + ); + } + + /// The launcher always passes the selected format so the parent and child + /// cannot silently drift onto different output formats. + #[test] + fn text_is_forwarded_to_the_child() { + for launcher in [ + SamlAuthLauncher::new("portal.example.com").log_format(LogFormat::Text), + SamlAuthLauncher::new("portal.example.com"), + ] { + let args = child_args(launcher); + + assert!( + args.windows(2).any(|pair| pair == ["--log-format", "text"]), + "expected --log-format text in {args:?}" + ); + } + } + #[test] fn client_certificate_options_are_stored() { let launcher = SamlAuthLauncher::new("portal.example.com") diff --git a/flake.lock b/flake.lock index 9f7f3c8..c2a0cf8 100644 --- a/flake.lock +++ b/flake.lock @@ -43,7 +43,9 @@ "naersk": { "inputs": { "fenix": "fenix", - "nixpkgs": "nixpkgs" + "nixpkgs": [ + "nixpkgs" + ] }, "locked": { "lastModified": 1763384566, @@ -60,22 +62,6 @@ } }, "nixpkgs": { - "locked": { - "lastModified": 1752077645, - "narHash": "sha256-HM791ZQtXV93xtCY+ZxG1REzhQenSQO020cu6rHtAPk=", - "owner": "NixOS", - "repo": "nixpkgs", - "rev": "be9e214982e20b8310878ac2baa063a961c1bdf6", - "type": "github" - }, - "original": { - "owner": "NixOS", - "ref": "nixpkgs-unstable", - "repo": "nixpkgs", - "type": "github" - } - }, - "nixpkgs_2": { "locked": { "lastModified": 1766410818, "narHash": "sha256-ruVneSx6wFy5PMw1ow3BE+znl653TJ6+eeNUj4B/9y8=", @@ -91,27 +77,11 @@ "type": "github" } }, - "nixpkgs_3": { - "locked": { - "lastModified": 1744536153, - "narHash": "sha256-awS2zRgF4uTwrOKwwiJcByDzDOdo3Q1rPZbiHQg/N38=", - "owner": "NixOS", - "repo": "nixpkgs", - "rev": "18dd725c29603f582cf1900e0d25f9f1063dbf11", - "type": "github" - }, - "original": { - "owner": "NixOS", - "ref": "nixpkgs-unstable", - "repo": "nixpkgs", - "type": "github" - } - }, "root": { "inputs": { "flake-utils": "flake-utils", "naersk": "naersk", - "nixpkgs": "nixpkgs_2", + "nixpkgs": "nixpkgs", "rust-overlay": "rust-overlay" } }, @@ -134,7 +104,9 @@ }, "rust-overlay": { "inputs": { - "nixpkgs": "nixpkgs_3" + "nixpkgs": [ + "nixpkgs" + ] }, "locked": { "lastModified": 1766457837, diff --git a/flake.nix b/flake.nix index 97b40ac..7d151c0 100644 --- a/flake.nix +++ b/flake.nix @@ -1,9 +1,15 @@ { inputs = { - flake-utils.url = "github:numtide/flake-utils"; - naersk.url = "github:nix-community/naersk"; nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; - rust-overlay.url = "github:oxalica/rust-overlay"; + flake-utils.url = "github:numtide/flake-utils"; + naersk = { + url = "github:nix-community/naersk"; + inputs.nixpkgs.follows = "nixpkgs"; + }; + rust-overlay = { + url = "github:oxalica/rust-overlay"; + inputs.nixpkgs.follows = "nixpkgs"; + }; }; outputs =