feat: add --log-format json to gpclient and gpauth (#644)

Co-authored-by: Kevin Yue <[email protected]>
This commit is contained in:
Ronald HötschlandKevin Yue authored and GitHub committed 2026-08-20 23:28:01 +08:00
1 parent 2283d4a076
commit f9f9dd8abe
11 files changed
+783 -48

No files matched your search

+8 -4
View File
@@ -55,13 +55,17 @@ Commands:
connect Connect to a portal server connect Connect to a portal server
disconnect Disconnect from the server disconnect Disconnect from the server
launch-gui Launch the GUI launch-gui Launch the GUI
hip Generate HIP report
help Print this message or the help of the given subcommand(s) help Print this message or the help of the given subcommand(s)
Options: Options:
--fix-openssl Get around the OpenSSL 'unsafe legacy renegotiation' error --fix-openssl Uses extended compatibility mode for OpenSSL operations to support a broader range of systems and formats.
--ignore-tls-errors Ignore TLS errors --ignore-tls-errors Ignore the TLS errors
-h, --help Print help --log-format <LOG_FORMAT> Log output format. JSON is intended for non-interactive consumers; interactive prompts remain text. [default: text] [possible values: text, json]
-V, --version Print version -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 <command>` for detailed information on a specific command. > **Tip:** Use `gpclient help <command>` for detailed information on a specific command.
+97 -5
View File
@@ -4,6 +4,7 @@ use gpapi::{
auth::{SamlAuthData, SamlAuthResult}, auth::{SamlAuthData, SamlAuthResult},
clap::{Args, InfoLevelVerbosity, args::Os, handle_error}, clap::{Args, InfoLevelVerbosity, args::Os, handle_error},
gp_params::GpParams, gp_params::GpParams,
log_format::{LogFormat, write_json_record},
os_profile::{ClientOs, OsProfile}, os_profile::{ClientOs, OsProfile},
utils::{normalize_server, openssl}, utils::{normalize_server, openssl},
}; };
@@ -76,6 +77,14 @@ struct Cli {
#[arg(long, help = "Ignore TLS errors")] #[arg(long, help = "Ignore TLS errors")]
ignore_tls_errors: bool, 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")] #[cfg(feature = "webview-auth")]
#[arg(long, help = "Use the default browser for authentication")] #[arg(long, help = "Use the default browser for authentication")]
default_browser: bool, default_browser: bool,
@@ -108,6 +117,10 @@ impl Args for Cli {
fn ignore_tls_errors(&self) -> bool { fn ignore_tls_errors(&self) -> bool {
self.ignore_tls_errors self.ignore_tls_errors
} }
fn log_format(&self) -> LogFormat {
self.log_format
}
} }
impl Cli { impl Cli {
@@ -205,16 +218,23 @@ impl Cli {
} }
} }
fn init_logger(cli: &Cli) { fn build_logger(cli: &Cli) -> env_logger::Builder {
env_logger::builder() let mut builder = env_logger::builder();
.filter_level(cli.verbose.log_level_filter()) builder.filter_level(cli.verbose.log_level_filter());
.init();
// 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() { pub async fn run() {
let cli = Cli::parse(); let cli = Cli::parse();
init_logger(&cli); build_logger(&cli).init();
info!("gpauth started: {}", VERSION); info!("gpauth started: {}", VERSION);
if let Err(err) = cli.run().await { if let Err(err) = cli.run().await {
@@ -240,8 +260,80 @@ pub fn print_auth_result(auth_result: anyhow::Result<SamlAuthData>, host_id: Opt
#[cfg(test)] #[cfg(test)]
mod tests { mod tests {
use std::{
io::Write,
sync::{Arc, Mutex},
};
use log::Log;
use super::*; 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<Mutex<Vec<u8>>>);
impl Write for Captured {
fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
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] #[test]
fn os_defaults_to_runtime_os() { fn os_defaults_to_runtime_os() {
let cli = Cli::try_parse_from(["gpauth", "portal.example.com"]).expect("gpauth args should parse"); let cli = Cli::try_parse_from(["gpauth", "portal.example.com"]).expect("gpauth args should parse");
+137 -3
View File
@@ -4,6 +4,7 @@ use anyhow::bail;
use clap::{Parser, Subcommand}; use clap::{Parser, Subcommand};
use gpapi::{ use gpapi::{
clap::{Args, InfoLevelVerbosity, handle_error}, clap::{Args, InfoLevelVerbosity, handle_error},
log_format::{LogFormat, write_json_record},
utils::openssl, utils::openssl,
}; };
use log::info; use log::info;
@@ -32,6 +33,7 @@ pub(crate) struct SharedArgs<'a> {
pub(crate) fix_openssl: bool, pub(crate) fix_openssl: bool,
pub(crate) ignore_tls_errors: bool, pub(crate) ignore_tls_errors: bool,
pub(crate) verbose: &'a InfoLevelVerbosity, pub(crate) verbose: &'a InfoLevelVerbosity,
pub(crate) log_format: LogFormat,
} }
#[derive(Subcommand)] #[derive(Subcommand)]
@@ -76,6 +78,14 @@ struct Cli {
#[arg(long, help = "Ignore the TLS errors")] #[arg(long, help = "Ignore the TLS errors")]
ignore_tls_errors: bool, 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)] #[command(flatten)]
verbose: InfoLevelVerbosity, verbose: InfoLevelVerbosity,
} }
@@ -88,6 +98,10 @@ impl Args for Cli {
fn ignore_tls_errors(&self) -> bool { fn ignore_tls_errors(&self) -> bool {
self.ignore_tls_errors self.ignore_tls_errors
} }
fn log_format(&self) -> LogFormat {
self.log_format
}
} }
impl Cli { impl Cli {
@@ -132,6 +146,7 @@ impl Cli {
fix_openssl: self.fix_openssl, fix_openssl: self.fix_openssl,
ignore_tls_errors: self.ignore_tls_errors, ignore_tls_errors: self.ignore_tls_errors,
verbose: &self.verbose, verbose: &self.verbose,
log_format: self.log_format,
}; };
if self.ignore_tls_errors { 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(); let mut builder = env_logger::builder();
builder.filter_level(cli.verbose.log_level_filter()); 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 // Output the log messages to a file if the command is the auth callback
if let CliCommand::LaunchGui(args) = &cli.command { if let CliCommand::LaunchGui(args) = &cli.command {
let auth_data = args.auth_data.as_deref().unwrap_or_default(); 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() { pub(crate) async fn run() {
let cli = Cli::parse(); let cli = Cli::parse();
init_logger(&cli); build_logger(&cli).init();
info!("gpclient started: {}", VERSION); info!("gpclient started: {}", VERSION);
@@ -177,3 +198,116 @@ pub(crate) async fn run() {
std::process::exit(1); 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<Mutex<Vec<u8>>>);
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<usize> {
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::<serde_json::Value>(out.trim()).is_err(),
"text output should not be JSON: {out:?}"
);
}
}
+1
View File
@@ -85,6 +85,7 @@ impl ConnectHandler<'_> {
.sslkey(self.args.sslkey.as_deref()) .sslkey(self.args.sslkey.as_deref())
.key_password(key_password.as_deref()) .key_password(key_password.as_deref())
.browser(browser) .browser(browser)
.log_format(self.shared_args.log_format)
.verbose(verbose); .verbose(verbose);
#[cfg(feature = "webview-auth")] #[cfg(feature = "webview-auth")]
+20 -5
View File
@@ -7,6 +7,7 @@ use std::{
}; };
use gpapi::{ use gpapi::{
clap::report,
cookie_store, cookie_store,
credential::{AuthCookieCredential, Credential}, credential::{AuthCookieCredential, Credential},
gateway::{GatewayLogin, GatewayLoginContext, SessionExtensionAuth, gateway_login, gateway_login_with_context}, gateway::{GatewayLogin, GatewayLoginContext, SessionExtensionAuth, gateway_login, gateway_login_with_context},
@@ -17,7 +18,7 @@ use gpapi::{
utils::shutdown_signal, utils::shutdown_signal,
}; };
use inquire::Text; use inquire::Text;
use log::{info, warn}; use log::{Level, info, warn};
use openconnect::{Vpn, VpnBuilder}; use openconnect::{Vpn, VpnBuilder};
use tokio::{runtime::Handle, task::JoinHandle}; use tokio::{runtime::Handle, task::JoinHandle};
@@ -281,9 +282,22 @@ impl ConnectHandler<'_> {
return; return;
} }
eprintln!("\nNOTE: Gateway authentication failed after portal login."); let format = self.shared_args.log_format;
eprintln!("NOTE: If this server also accepts direct gateway login, try:"); report(
eprintln!("NOTE: {}", direct_gateway_command(gateway)); 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( async fn login_gateway(
@@ -384,6 +398,7 @@ impl ConnectHandler<'_> {
vpn_clone.disconnect(); vpn_clone.disconnect();
}); });
let log_format = self.shared_args.log_format;
let connect_result = vpn.connect(move |vpn_session_info| { let connect_result = vpn.connect(move |vpn_session_info| {
tunnel_established_on_connect.store(true, Ordering::SeqCst); tunnel_established_on_connect.store(true, Ordering::SeqCst);
write_pid_file(); write_pid_file();
@@ -394,7 +409,7 @@ impl ConnectHandler<'_> {
let session_info = session_info_from_vpn(vpn_session_info, allow_extend_session); let session_info = session_info_from_vpn(vpn_session_info, allow_extend_session);
info!("VPN session info: {}", session_info.log_summary()); 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); session_task_on_connect.lock().unwrap().replace(task);
}); });
let tunnel_established = tunnel_established.load(Ordering::SeqCst); let tunnel_established = tunnel_established.load(Ordering::SeqCst);
+24 -5
View File
@@ -6,6 +6,7 @@ use std::cell::RefCell;
use anyhow::bail; use anyhow::bail;
use gpapi::{ use gpapi::{
clap::report,
error::PortalError, error::PortalError,
gateway::{GatewayLoginContext, GatewaySelection}, gateway::{GatewayLoginContext, GatewaySelection},
gp_params::GpParams, gp_params::GpParams,
@@ -14,7 +15,7 @@ use gpapi::{
utils::request::RequestIdentityError, utils::request::RequestIdentityError,
}; };
use inquire::{Password, PasswordDisplayMode, Select}; use inquire::{Password, PasswordDisplayMode, Select};
use log::{info, warn}; use log::{Level, info, warn};
use crate::cli::SharedArgs; use crate::cli::SharedArgs;
@@ -110,8 +111,17 @@ impl<'a> ConnectHandler<'a> {
match root_cause { match root_cause {
RequestIdentityError::NoKey => { RequestIdentityError::NoKey => {
eprintln!("ERROR: No private key found in the certificate file"); let format = self.shared_args.log_format;
eprintln!("ERROR: Please provide the private key file using the `-k` option"); 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(()); return Ok(());
} }
RequestIdentityError::NoPassphrase(cert_type) | RequestIdentityError::DecryptError(cert_type) => { RequestIdentityError::NoPassphrase(cert_type) | RequestIdentityError::DecryptError(cert_type) => {
@@ -153,8 +163,17 @@ impl<'a> ConnectHandler<'a> {
info!("Trying the gateway authentication workflow..."); info!("Trying the gateway authentication workflow...");
self.connect_gateway_with_prelogin(server, server, false, None).await?; self.connect_gateway_with_prelogin(server, server, false, None).await?;
eprintln!("\nNOTE: the server may be a gateway, not a portal."); let format = self.shared_args.log_format;
eprintln!("NOTE: try to use the `--as-gateway` option if you were authenticated twice."); 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(()) Ok(())
} else { } else {
+13 -6
View File
@@ -1,11 +1,13 @@
use std::time::{Duration, SystemTime, UNIX_EPOCH}; use std::time::{Duration, SystemTime, UNIX_EPOCH};
use gpapi::{ use gpapi::{
clap::report,
gateway::{SessionContext, SessionExtensionAuth, extend_session}, gateway::{SessionContext, SessionExtensionAuth, extend_session},
log_format::LogFormat,
os_profile::OsProfile, os_profile::OsProfile,
session::{SessionInfo, SessionRequestArgs, SessionWarning}, session::{SessionInfo, SessionRequestArgs, SessionWarning},
}; };
use log::{info, warn}; use log::{Level, info, warn};
use openconnect::VpnSessionInfo; use openconnect::VpnSessionInfo;
use tokio::{runtime::Handle, task::JoinHandle}; use tokio::{runtime::Handle, task::JoinHandle};
@@ -59,11 +61,12 @@ pub(crate) fn spawn_session_runtime_with_info(
handle: &Handle, handle: &Handle,
session_ctx: SessionContext, session_ctx: SessionContext,
session_info: SessionInfo, session_info: SessionInfo,
log_format: LogFormat,
) -> JoinHandle<()> { ) -> 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 { loop {
let Some(schedule) = build_session_warning_schedule(&session_info) else { let Some(schedule) = build_session_warning_schedule(&session_info) else {
info!("No session warning schedule provided by the gateway"); 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; tokio::time::sleep(schedule.delay).await;
eprintln!("\nWARNING: {}", schedule.message); report(log_format, Level::Warn, &format!("\nWARNING: {}", schedule.message));
if !schedule.should_auto_extend { if !schedule.should_auto_extend {
info!("Session extension is not allowed by the gateway"); 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; return;
}; };
eprintln!("Session extended."); report(log_format, Level::Info, "Session extended.");
session_info = next_session_info; session_info = next_session_info;
} }
Err(err) => { Err(err) => {
warn!("Failed to extend session: {}", 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; return;
} }
} }
+243 -11
View File
@@ -1,33 +1,139 @@
use std::io::{self, Write};
use clap_verbosity_flag::{LogLevel, Verbosity, VerbosityFilter}; use clap_verbosity_flag::{LogLevel, Verbosity, VerbosityFilter};
use log::Level; use log::Level;
use crate::error::PortalError; use crate::{
error::PortalError,
log_format::{LogFormat, write_json_record},
};
pub mod args; pub mod args;
pub trait Args { pub trait Args {
fn fix_openssl(&self) -> bool; fn fix_openssl(&self) -> bool;
fn ignore_tls_errors(&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) { /// Suggestions for re-running the command, for failures that have a known
eprintln!("\nError: {:?}", err); /// 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<String> {
let Some(err) = err.downcast_ref::<PortalError>() else { let Some(err) = err.downcast_ref::<PortalError>() else {
return; return Vec::new();
}; };
let command_line = || {
let argv = std::env::args().collect::<Vec<_>>();
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() { 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 (program, rest) = command_line();
let args = std::env::args().collect::<Vec<_>>(); hints.push(format!(
eprintln!("{} --fix-openssl {}\n", args[0], args[1..].join(" ")); "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() { 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 (program, rest) = command_line();
let args = std::env::args().collect::<Vec<_>>(); hints.push(format!(
eprintln!("{} --ignore-tls-errors {}\n", args[0], args[1..].join(" ")); "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: Write>(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: Write>(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: Write>(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)] #[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::<serde_json::Value>(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::<serde_json::Value>(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::<serde_json::Value>(text.trim()).is_err(),
"text mode must not emit JSON: {text:?}"
);
}
}
+1
View File
@@ -4,6 +4,7 @@ pub mod credential;
pub mod error; pub mod error;
pub mod gateway; pub mod gateway;
pub mod gp_params; pub mod gp_params;
pub mod log_format;
pub mod os_profile; pub mod os_profile;
pub mod params; pub mod params;
pub mod portal; pub mod portal;
+164
View File
@@ -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: Write>(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);
}
}
}
+75 -9
View File
@@ -1,10 +1,13 @@
use std::{path::PathBuf, process::Stdio}; use std::{
path::{Path, PathBuf},
process::Stdio,
};
use anyhow::bail; use anyhow::bail;
use common::binary_paths; use common::binary_paths;
use tokio::process::Command; 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; use super::command_traits::CommandExt;
@@ -29,6 +32,7 @@ pub struct SamlAuthLauncher<'a> {
default_browser: bool, default_browser: bool,
browser: Option<&'a str>, browser: Option<&'a str>,
verbose: Option<&'a str>, verbose: Option<&'a str>,
log_format: LogFormat,
} }
impl<'a> SamlAuthLauncher<'a> { impl<'a> SamlAuthLauncher<'a> {
@@ -54,6 +58,7 @@ impl<'a> SamlAuthLauncher<'a> {
default_browser: false, default_browser: false,
browser: None, browser: None,
verbose: None, verbose: None,
log_format: LogFormat::Text,
} }
} }
@@ -127,18 +132,27 @@ impl<'a> SamlAuthLauncher<'a> {
self 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 { pub fn verbose(mut self, verbose: Option<&'a str>) -> Self {
self.verbose = verbose; self.verbose = verbose;
self self
} }
/// Launch the authenticator binary as the current user or SUDO_USER if available. /// The command line this launcher will run.
pub async fn launch(self) -> anyhow::Result<Credential> { ///
let program = self /// Split out from `launch` so a test can observe the argv the child actually
.auth_executable /// receives: asserting on the builder's own fields would not catch an
.map(PathBuf::from) /// argument that never gets appended.
.unwrap_or_else(binary_paths::gpauth); fn build_command(&self, program: &Path) -> Command {
let mut auth_cmd = Command::new(&program); let mut auth_cmd = Command::new(program);
auth_cmd.arg(self.server); auth_cmd.arg(self.server);
if self.gateway { if self.gateway {
@@ -200,10 +214,23 @@ impl<'a> SamlAuthLauncher<'a> {
auth_cmd.arg("--browser").arg(browser); auth_cmd.arg("--browser").arg(browser);
} }
auth_cmd.arg("--log-format").arg(self.log_format.as_str());
if let Some(verbose) = self.verbose { if let Some(verbose) = self.verbose {
auth_cmd.arg(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<Credential> {
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 mut non_root_cmd = auth_cmd.into_non_root()?;
let child = non_root_cmd.kill_on_drop(true).stdout(Stdio::piped()).spawn(); 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")); assert_eq!(launcher.client_version, Some("6.0.0"));
} }
fn child_args(launcher: SamlAuthLauncher) -> Vec<String> {
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] #[test]
fn client_certificate_options_are_stored() { fn client_certificate_options_are_stored() {
let launcher = SamlAuthLauncher::new("portal.example.com") let launcher = SamlAuthLauncher::new("portal.example.com")