Files
GlobalProtect-openconnect/crates/gpapi/src/log_format.rs
T
2026-10-09 18:21:44 +08:00

165 lines
5.3 KiB
Rust

//! 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);
}
}
}