Files
ssw-mpc/crates/mpc-cli/src/report.rs
T
admin 54781b3f83
ci / gate (push) Waiting to run
refactor: 项目改名 ssw-mpc,crate 统一到 mpc-* 前缀
- 项目与文档标题:nax-rs → ssw-mpc(尚数网-多方安全计算),二进制 nax → mpc
- 18 个 crate 及目录 nax-* → mpc-*,Rust 引用 nax_* → mpc_*
- 环境变量、C 符号、构建/部署脚本:NAX_* → MPC_*、libnax_ray.so → libmpc_ray.so
- 保留协议域分隔常量与 refs/nax 参考实现路径,维持 golden 向量与历史数据兼容
- 新增 [profile.dev] incremental=false
2026-11-05 15:06:12 +08:00

427 lines
13 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! 统一报告输出:`--report json` 下所有结构化结果走同一套 schema。
//!
//! # 为什么要有这一层
//!
//! 之前每个子命令自己拼 `println!`,结果是「人看还行、机器没法吃」——
//! 想把 `mpc fl` 的逐轮 loss 画条曲线,得正则去扒终端输出。
//! SecretFlow 那边把结果塞进 protobuf 的 `REPORT` 域(`spec` 仓定义的
//! `Table` / `Histogram` 几种),mpc 没有 IDL,就用最小 JSON 表达同一件事。
//!
//! # 约定
//!
//! - **进度/诊断**一律 [`note`]:文本模式打 stdout,`--report json` 模式改打 stderr。
//! 这样 stdout 是纯 JSON 流,一行一个对象(NDJSON),`jq .` 能直接消费;
//! 一次命令产出多张表(如 `mpc fl` 的逐轮曲线 + 最终权重)也合法。
//! - **结构化结果**一律 [`table`] / [`kv`],schema 固定:
//!
//! ```json
//! {"kind":"table","title":"…","header":["a","b"],"rows":[[1,2.5]]}
//! {"kind":"kv","title":"…","rows":[["k","v"]]}
//! ```
//!
//! 两者都是「行列」,`kv` 只是 `header` 恒为 `["key","value"]` 的简写,
//! 单独留一个 `kind` 是为了让消费方(看板、`jq` 过滤)不必猜。
//!
//! # 不做什么
//!
//! 不引 `serde`。JSON 的产出面就这么点(表、键值、字符串转义),
//! 自己写 40 行比带一棵依赖树便宜,也和「单二进制、零依赖」的调子一致。
use std::fmt;
use std::io::Write;
use std::sync::atomic::{AtomicBool, Ordering};
/// `--report json` 是否生效。
static JSON: AtomicBool = AtomicBool::new(false);
/// 由 `main` 在分发子命令前设定一次。
pub fn set_json(on: bool) {
JSON.store(on, Ordering::Relaxed);
}
/// 当前是否 JSON 模式。
pub fn is_json() -> bool {
JSON.load(Ordering::Relaxed)
}
/// 打一行进度/诊断。
///
/// 文本模式进 stdout(保持原有观感),JSON 模式进 stderr(不污染数据流)。
/// 写失败一律忽略 —— `mpc fl | head -5` 会触发 EPIPE,此时该安静退出而不是 panic。
pub fn note(args: fmt::Arguments<'_>) {
if is_json() {
let _ = writeln!(std::io::stderr(), "{args}");
} else {
let _ = writeln!(std::io::stdout().lock(), "{args}");
}
}
/// 同 [`note`],但不换行(`print!` 的对应物)。
#[allow(dead_code)]
pub fn note_inline(args: fmt::Arguments<'_>) {
if is_json() {
let _ = write!(std::io::stderr(), "{args}");
let _ = std::io::stderr().flush();
} else {
let mut out = std::io::stdout().lock();
let _ = write!(out, "{args}");
let _ = out.flush();
}
}
// ---------------------------------------------------------------------------
// 单元格
// ---------------------------------------------------------------------------
/// 表格里的一个格子。
///
/// 数字单独成类(而不是先格式化成字符串)是为了照顾两边:
/// 文本模式要按人习惯截到固定小数位,JSON 模式要能被 `jq` 当数字算。
#[derive(Debug, Clone)]
pub enum Cell {
/// 字符串。
Text(String),
/// 浮点:`prec` 只在文本模式生效,JSON 走最短往返表示。
Num { v: f64, prec: usize },
/// 整数。
Int(i64),
/// 布尔。
Bool(bool),
/// 空值:文本模式显示括号里的说明(如 `(空集)`),JSON 出 `null`。
Null(String),
}
impl Cell {
/// 字符串格。
pub fn txt(s: impl Into<String>) -> Self {
Self::Text(s.into())
}
/// 浮点格,指定文本精度(JSON 一律走最短往返表示,不受 `prec` 影响)。
pub fn nump(v: f64, prec: usize) -> Self {
Self::Num { v, prec }
}
/// 整数格。
pub fn int(v: impl Into<i64>) -> Self {
Self::Int(v.into())
}
/// 布尔格。
pub fn flag(b: bool) -> Self {
Self::Bool(b)
}
/// 空值格,文本模式显示 `(说明)`。
pub fn empty(why: impl Into<String>) -> Self {
Self::Null(why.into())
}
fn as_text(&self) -> String {
match self {
Self::Text(s) => s.clone(),
Self::Num { v, prec } => {
if v.is_finite() {
format!("{v:.prec$}")
} else {
// 文本模式给个可读的记号;JSON 那边会变成 null
format!("{v}")
}
}
Self::Int(i) => i.to_string(),
Self::Bool(b) => b.to_string(),
Self::Null(why) => format!("({why})"),
}
}
fn is_numeric(&self) -> bool {
matches!(self, Self::Num { .. } | Self::Int(_))
}
fn write_json(&self, out: &mut String) {
match self {
Self::Text(s) => write_str_json(s, out),
Self::Num { v, .. } => {
if v.is_finite() {
// Display for f64 给的是最短且能往返的表示,正好是合法 JSON 数字
out.push_str(&format!("{v}"));
} else {
// JSON 没有 NaN/Infinity,降级成 null 比编个字符串诚实
out.push_str("null");
}
}
Self::Int(i) => out.push_str(&i.to_string()),
Self::Bool(b) => out.push_str(if *b { "true" } else { "false" }),
Self::Null(_) => out.push_str("null"),
}
}
}
impl From<&str> for Cell {
fn from(s: &str) -> Self {
Self::Text(s.to_string())
}
}
impl From<String> for Cell {
fn from(s: String) -> Self {
Self::Text(s)
}
}
// ---------------------------------------------------------------------------
// JSON 拼装
// ---------------------------------------------------------------------------
/// 写一个 JSON 字符串字面量(含两边的引号)。
fn write_str_json(s: &str, out: &mut String) {
out.push('"');
for c in s.chars() {
match c {
'"' => out.push_str("\\\""),
'\\' => out.push_str("\\\\"),
'\n' => out.push_str("\\n"),
'\r' => out.push_str("\\r"),
'\t' => out.push_str("\\t"),
c if (c as u32) < 0x20 => {
out.push_str(&format!("\\u{:04x}", c as u32));
}
c => out.push(c),
}
}
out.push('"');
}
fn write_rows_json(header: &[&str], rows: &[Vec<Cell>], out: &mut String) {
out.push_str("\"header\":[");
for (i, h) in header.iter().enumerate() {
if i > 0 {
out.push(',');
}
write_str_json(h, out);
}
out.push_str("],\"rows\":[");
for (i, row) in rows.iter().enumerate() {
if i > 0 {
out.push(',');
}
out.push('[');
for (j, cell) in row.iter().enumerate() {
if j > 0 {
out.push(',');
}
cell.write_json(out);
}
out.push(']');
}
out.push_str("]}");
}
fn emit(line: &str) {
let mut out = std::io::stdout().lock();
let _ = writeln!(out, "{line}");
let _ = out.flush();
}
/// 输出一张表。文本模式画对齐的表格,JSON 模式输出一个 `kind:"table"` 对象。
///
/// 列对齐按内容决定:整列都是数字就右对齐、否则左对齐。
/// 宽度按**显示宽度**算(CJK 记 2),否则中文表头下面那行会歪。
pub fn table(title: &str, header: &[&str], rows: &[Vec<Cell>]) {
if is_json() {
emit(&table_json(title, header, rows));
return;
}
let mut text: Vec<Vec<String>> = rows.iter().map(|r| r.iter().map(Cell::as_text).collect()).collect();
// 行宽不足时补空串,避免下面按下标取越界
for r in text.iter_mut() {
while r.len() < header.len() {
r.push(String::new());
}
}
let mut widths: Vec<usize> = header.iter().map(|h| disp_width(h)).collect();
for r in &text {
for (i, c) in r.iter().enumerate().take(widths.len()) {
widths[i] = widths[i].max(disp_width(c));
}
}
let right: Vec<bool> = (0..header.len())
.map(|i| {
let non_empty: Vec<&Cell> = rows.iter().filter_map(|r| r.get(i)).collect();
!non_empty.is_empty() && non_empty.iter().all(|c| c.is_numeric())
})
.collect();
let mut out = String::new();
if !title.is_empty() {
out.push_str(title);
out.push('\n');
}
// 表头
let head: Vec<String> = header
.iter()
.enumerate()
.map(|(i, h)| pad(h, widths[i], right[i]))
.collect();
out.push_str(head.join(" | ").trim_end());
out.push('\n');
let sep: Vec<String> = widths.iter().map(|w| "-".repeat(*w)).collect();
out.push_str(&sep.join("-+-"));
out.push('\n');
for r in &text {
let cells: Vec<String> = r
.iter()
.enumerate()
.take(header.len())
.map(|(i, c)| pad(c, widths[i], right[i]))
.collect();
// 末列右侧补的空格没人要,还会让复制出来的内容带尾巴
out.push_str(cells.join(" | ").trim_end());
out.push('\n');
}
let _ = std::io::stdout().lock().write_all(out.as_bytes());
}
/// 输出键值对(`header` 固定为 `key`/`value`)。
pub fn kv(title: &str, rows: &[(&str, Cell)]) {
let owned: Vec<Vec<Cell>> = rows
.iter()
.map(|(k, v)| vec![Cell::txt(*k), v.clone()])
.collect();
table(title, &["key", "value"], &owned);
}
// ---------------------------------------------------------------------------
// 对齐辅助
// ---------------------------------------------------------------------------
/// 终端显示宽度:CJK / 全角按 2 列算。
///
/// 只覆盖常见区间。不做完整的 East Asian Width 表 —— 表格里出现的
/// 非 ASCII 字符基本就是中文和全角标点,够用。
fn disp_width(s: &str) -> usize {
s.chars()
.map(|c| {
let u = c as u32;
let wide = matches!(u,
0x1100..=0x115F
| 0x2E80..=0x303E
| 0x3041..=0x33FF
| 0x3400..=0x4DBF
| 0x4E00..=0x9FFF
| 0xA000..=0xA4CF
| 0xAC00..=0xD7A3
| 0xF900..=0xFAFF
| 0xFE30..=0xFE6F
| 0xFF00..=0xFF60
| 0xFFE0..=0xFFE6);
if wide {
2
} else {
1
}
})
.sum()
}
fn pad(s: &str, width: usize, right: bool) -> String {
let w = disp_width(s);
if w >= width {
return s.to_string();
}
let fill = " ".repeat(width - w);
if right {
format!("{fill}{s}")
} else {
format!("{s}{fill}")
}
}
// ---------------------------------------------------------------------------
// 把表的 JSON 拼出来(给测试用,也给将来写文件留口子)
// ---------------------------------------------------------------------------
/// 返回 `table` 在 JSON 模式下会输出的那一行,不打印。
pub fn table_json(title: &str, header: &[&str], rows: &[Vec<Cell>]) -> String {
let mut s = String::from("{\"kind\":\"table\",\"title\":");
write_str_json(title, &mut s);
s.push(',');
write_rows_json(header, rows, &mut s);
s
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn escapes_quotes_backslash_and_controls() {
let mut s = String::new();
write_str_json("a\"b\\c\nd\te\u{1}", &mut s);
assert_eq!(s, r#""a\"b\\c\nd\te\u0001""#);
}
#[test]
fn non_finite_becomes_null_in_json() {
let mut s = String::new();
Cell::nump(f64::NAN, 4).write_json(&mut s);
assert_eq!(s, "null");
s.clear();
Cell::nump(f64::INFINITY, 4).write_json(&mut s);
assert_eq!(s, "null");
// 文本模式仍要给个记号,否则用户只看到空白
assert_eq!(Cell::nump(f64::NAN, 4).as_text(), "NaN");
}
#[test]
fn null_cell_shows_reason_in_text_only() {
let c = Cell::empty("空集");
assert_eq!(c.as_text(), "(空集)");
let mut s = String::new();
c.write_json(&mut s);
assert_eq!(s, "null");
}
#[test]
fn table_json_has_planned_shape() {
let rows = vec![
vec![Cell::int(1), Cell::nump(0.5, 4), Cell::txt("ok")],
vec![Cell::int(2), Cell::nump(0.75, 4), Cell::flag(true)],
];
let got = table_json("训练", &["轮", "loss", "状态"], &rows);
assert_eq!(
got,
r#"{"kind":"table","title":"训练","header":["轮","loss","状态"],"rows":[[1,0.5,"ok"],[2,0.75,true]]}"#
);
}
#[test]
fn cjk_counts_as_two_columns() {
assert_eq!(disp_width("abc"), 3);
assert_eq!(disp_width("轮次"), 4);
assert_eq!(disp_width("w[0]"), 4);
}
#[test]
fn pad_respects_display_width() {
assert_eq!(pad("轮次", 6, false), "轮次 ");
assert_eq!(pad("1.5", 5, true), " 1.5");
// 已经超宽就不截断(宁可歪,不要丢信息)
assert_eq!(pad("12345", 3, true), "12345");
}
#[test]
fn numeric_column_detected_for_alignment() {
let rows = vec![
vec![Cell::int(1), Cell::txt("x")],
vec![Cell::int(22), Cell::txt("y")],
];
let right: Vec<bool> = (0..2)
.map(|i| rows.iter().filter_map(|r| r.get(i)).all(|c| c.is_numeric()))
.collect();
assert_eq!(right, vec![true, false]);
}
}