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
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_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 <command>` for detailed information on a specific command.
+97 -5
View File
@@ -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<SamlAuthData>, 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<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]
fn os_defaults_to_runtime_os() {
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 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<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())
.key_password(key_password.as_deref())
.browser(browser)
.log_format(self.shared_args.log_format)
.verbose(verbose);
#[cfg(feature = "webview-auth")]
+20 -5
View File
@@ -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);
+24 -5
View File
@@ -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 {
+13 -6
View File
@@ -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;
}
}
+243 -11
View File
@@ -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<String> {
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() {
eprintln!("\nRe-run it with the `--fix-openssl` option to work around this issue, e.g.:\n");
let args = std::env::args().collect::<Vec<_>>();
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::<Vec<_>>();
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: 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)]
@@ -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 gateway;
pub mod gp_params;
pub mod log_format;
pub mod os_profile;
pub mod params;
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 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<Credential> {
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<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 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<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]
fn client_certificate_options_are_stored() {
let launcher = SamlAuthLauncher::new("portal.example.com")