diff --git a/architecture/notes/pebrel_app/recent_output/2026-09-21-bounded-local-output.md b/architecture/notes/pebrel_app/recent_output/2026-09-21-bounded-local-output.md new file mode 100644 index 000000000..a7e48809c --- /dev/null +++ b/architecture/notes/pebrel_app/recent_output/2026-09-21-bounded-local-output.md @@ -0,0 +1,65 @@ +# 静态输出快照与本机引用的持久化边界 + +## Status + +供审核的持久化基础;尚未接入命令采集、设置控件或窗口输出恢复。 +关联 #160,本阶段不代表完整功能已交付。 + +## Context + +终端显示、输出文件和布局会话的生命周期不同。多个 pane 可以处于同一目录, +因此目录不能作为旧输出归属。直接回放原始 VT 会再次执行控制动作; +把输出及引用放进共享工作区格式,又会让导出携带本机历史。 + +## Evidence + +- [显示快照与校验](../../../../pebrel_terminal/src/grid/snapshot.rs)覆盖 Unicode 重排、容量和控制数据拒绝;备用屏活动时读取主屏由第二项随采集接入。 +- [有界输出存储](../../../../pebrel_app/src/recent_output/storage.rs)复用原子文件写入。 +- [发布生命周期](../../../../pebrel_app/src/recent_output/storage/lifecycle.rs)的回归测试覆盖两代交接、失败重试和发布回调内失效。 +- 本机会话引用(`session/local_output.rs`)随第二项的逐 pane 采集交付;本项存储测试以普通文件代替会话,只验证发布回调的提交语义。 + +## Decision + +terminal 层仅捕获和恢复主屏的静态显示字段,恢复到历史区,不重放 VT, +不改活终端屏幕或光标。反序列化与恢复先校验结构、容量和控制数据。 + +app 层以独立 sidecar 保存有界记录,每 pane 最多五条,每条最多 256 KiB。 +正常归档最多 16 MiB,两代原子交接最多 32 MiB;超量先裁剪旧记录再生成引用。 +读取 sidecar 时,解码器逐项检查 pane 引用、每个 pane 的记录数和每条记录的编码大小。它只接收一代交接数据;重复引用会使归档无效。 +精确引用只属于本机自动恢复文档,共享工作区的导入和导出不携带这些引用。 + +先持久化输出,再发布会话引用,发布成功前保留旧引用可读取的那一代。 +发布失败恢复旧归档;成功后才能回收旧代。回调成功意味着会话已经落盘, +即使回调内代次失效,也必须报告真实的持久化结果并保留交接数据。 +后续接入者负责通过同一串行边界提交新的 checkpoint;无引用 checkpoint +不能等同清除全部旧历史,显式清除使用独立操作。 + +## Rejected alternatives + +- 回放原始 VT:会重放控制动作,无法保证只恢复显示。 +- 按 cwd 匹配:同目录多 pane 无法确定归属。 +- 在共享会话中嵌入输出或本机引用:扩大导出范围和载入成本。 +- 发布引用前覆盖旧代:中断后旧会话可能引用已丢失的数据。 +- 发布成功后仅凭代次变化返回未提交:内存结果会与实际磁盘状态矛盾。 + +## Consequences + +存储和终端边界可各自验证,后续采集及窗口接入复用同一规则。 +本阶段不会自动记录命令或恢复终端输出,也不新增用户设置。 +调用方须在后台执行磁盘操作,并承担持久化完成后的生命周期收尾。 + +## Validation + +Windows 上实际运行:存储 24 项、会话相关 105 项、启动恢复 1 项通过; +`cargo test --locked -p nebula_terminal --features serde` 的 352 项通过, +包含使用现有打包资产执行的 ConPTY 生命周期测试。 +应用测试启用 `gpui-test-support`;仅关闭应用测试目标的调试符号,断言不变。 +这些结果验证本阶段边界,不作为尚未接入的窗口输出恢复验收。 + +## Supersedes + +None。 + +## Revisit when + +需要改变容量、引用身份、原子交接协议,或允许跨设备导出输出时重新审核。 diff --git a/pebrel_app/AGENTS.md b/pebrel_app/AGENTS.md index 2c76acdfe..e342a9661 100644 --- a/pebrel_app/AGENTS.md +++ b/pebrel_app/AGENTS.md @@ -38,3 +38,5 @@ - Windows Acrylic 的动画期间透明回退与计时边界见 [`窗口状态切换`](../architecture/notes/pebrel_app/platform/2026-09-22-acrylic-window-transitions.md)。 - 登录项的启动意图与首窗静默边界见 [`登录启动`](../architecture/notes/pebrel_app/platform/startup/2026-10-10-login-launch-intent.md)。 - OSC 8 本地链接的 C1 损坏恢复、显式链接身份与后台匹配边界见 [`file_uri`](../architecture/notes/pebrel_app/file_uri/2026-11-11-c1-corrupted-osc8-file-links.md)。 + +- 本机命令输出归档的代次、容量与发布顺序见 [最近输出的持久化边界](../architecture/notes/pebrel_app/recent_output/2026-09-21-bounded-local-output.md)。 diff --git a/pebrel_app/src/main.rs b/pebrel_app/src/main.rs index 948776f1c..c5a7b8ddf 100644 --- a/pebrel_app/src/main.rs +++ b/pebrel_app/src/main.rs @@ -109,6 +109,7 @@ mod profile_launch; mod prompt_suggestions; mod provider_test; mod proxy_test; +mod recent_output; mod remote_dirs; mod render_cache; #[cfg(feature = "legacy-shell")] diff --git a/pebrel_app/src/recent_output.rs b/pebrel_app/src/recent_output.rs new file mode 100644 index 000000000..8816cbd7b --- /dev/null +++ b/pebrel_app/src/recent_output.rs @@ -0,0 +1,257 @@ +//! 逐终端的有界命令显示记录;调用方只提交已确认的 shell 命令。 + +use pebrel_terminal::grid::snapshot::DisplaySnapshot; +use pebrel_terminal::grid::{Dimensions, Grid}; +use pebrel_terminal::index::Line; +use pebrel_terminal::term::cell::{Cell, Flags}; +use serde::{Deserialize, Serialize}; + +pub(crate) mod storage; + +const MAX_RECORDS: usize = 5; +const MAX_RECORD_BYTES: usize = 256 * 1024; +const MAX_CAPTURE_CELLS: usize = 4096; + +// 仅在保存边界编码,按整行缩小,避免切断 UTF-8 或宽字符。 +fn capture_bounded( + grid: &Grid, + range: std::ops::Range, + byte_budget: usize, +) -> DisplaySnapshot { + let mut low = 0; + let mut high = MAX_CAPTURE_CELLS / grid.columns(); + let mut best = DisplaySnapshot::capture(grid, range.clone(), 0); + while low <= high { + let rows = low + (high - low) / 2; + let candidate = DisplaySnapshot::capture(grid, range.clone(), rows * grid.columns()); + if serde_json::to_vec(&candidate).is_ok_and(|bytes| bytes.len() <= byte_budget) { + best = candidate; + low = rows + 1; + } else if rows == 0 { + break; + } else { + high = rows - 1; + } + } + best +} + +#[derive(Clone, Debug, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub(crate) struct CommandRecord { + #[serde(default)] + pub(crate) captured_at: u64, + prompt: DisplaySnapshot, + output: DisplaySnapshot, +} + +#[derive(Default)] +pub(crate) struct RecentOutput { + records: Vec, + active_output_start: Option, +} + +impl RecentOutput { + pub(crate) fn begin(&mut self, grid: &Grid) { + let mut start = grid.cursor.point.line; + while start.0 > -(grid.history_size() as i32) + && grid[Line(start.0 - 1)][pebrel_terminal::index::Column(grid.columns() - 1)] + .flags + .contains(Flags::WRAPLINE) + { + start.0 -= 1; + } + let end = Line(grid.cursor.point.line.0 + 1); + if self.records.len() == MAX_RECORDS { + self.records.remove(0); + } + self.records.push(CommandRecord { + captured_at: std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .map_or(0, |duration| duration.as_micros().min(u64::MAX as u128) as u64), + prompt: capture_bounded(grid, start..end, MAX_RECORD_BYTES / 2), + output: DisplaySnapshot::capture(grid, end..end, 0), + }); + self.active_output_start = Some(grid.scrolled_out() + grid.history_size() + end.0 as usize); + } + + pub(crate) fn finish(&mut self, grid: &Grid) { + if let Some(output) = self.capture_active(grid, false) { + if let Some(record) = self.records.last_mut() { + record.output = output; + } + } + self.active_output_start = None; + } + + pub(crate) fn snapshot(&self, grid: &Grid) -> Vec { + let mut records = self.records.clone(); + if let Some(output) = self.capture_active(grid, true) { + if let Some(record) = records.last_mut() { + record.output = output; + } + } + records + } + + fn capture_active(&self, grid: &Grid, include_cursor: bool) -> Option { + let absolute = self.active_output_start?; + let origin = grid.scrolled_out() + grid.history_size(); + let start = (absolute as i128 - origin as i128).clamp(i32::MIN as i128, i32::MAX as i128); + let end = grid.cursor.point.line.0 + i32::from(include_cursor); + let prompt_bytes = serde_json::to_vec(&self.records.last()?.prompt).ok()?.len(); + // 为字段名、标点及采集时间预留空间,确保整条记录仍在预算内。 + let budget = MAX_RECORD_BYTES.saturating_sub(prompt_bytes + 64); + Some(capture_bounded(grid, Line(start as i32)..Line(end), budget)) + } + pub(crate) fn try_from_records(records: Vec) -> Result { + Self::validate_records(&records)?; + Ok(Self { records, active_output_start: None }) + } + + pub(crate) fn validate_records(records: &[CommandRecord]) -> Result<(), &'static str> { + if records.len() > MAX_RECORDS { + return Err("too many command records"); + } + for record in records { + let bytes = serde_json::to_vec(record).map_err(|_| "invalid command record")?; + if bytes.len() > MAX_RECORD_BYTES { + return Err("command record exceeds byte budget"); + } + } + Ok(()) + } + pub(crate) fn restore(&self, grid: &mut Grid) -> Result<(), &'static str> { + // 每次静态导入都插在现有历史之前,因此从最新记录的输出开始。 + for record in self.records.iter().rev() { + record.output.restore_scrollback(grid)?; + record.prompt.restore_scrollback(grid)?; + } + Ok(()) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use pebrel_terminal::event::VoidListener; + use pebrel_terminal::grid::Dimensions; + use pebrel_terminal::index::{Column, Line}; + use pebrel_terminal::term::{Config, Term}; + use pebrel_terminal::vte::ansi; + + pub(super) struct Size; + impl Dimensions for Size { + fn total_lines(&self) -> usize { + 4 + } + fn screen_lines(&self) -> usize { + 4 + } + fn columns(&self) -> usize { + 32 + } + } + + #[test] + fn retains_five_commands_with_output_in_order_without_reexecuting() { + let mut term = Term::new(Config::default(), &Size, VoidListener); + let mut parser: ansi::Processor = ansi::Processor::new(); + let mut recent = RecentOutput::default(); + for index in 0..7 { + parser.advance(&mut term, format!("C:>echo {index}").as_bytes()); + recent.begin(term.grid()); + parser.advance(&mut term, format!("\r\nresult{index}\r\n").as_bytes()); + recent.finish(term.grid()); + } + let records = recent.snapshot(term.grid()); + assert_eq!(records.len(), 5); + let mut target = Term::new(Config::default(), &Size, VoidListener); + RecentOutput::try_from_records(records).unwrap().restore(target.grid_mut()).unwrap(); + let text = target.bounds_to_string( + pebrel_terminal::index::Point::new( + Line(-(target.grid().history_size() as i32)), + Column(0), + ), + pebrel_terminal::index::Point::new(Line(-1), Column(31)), + ); + assert!(!text.contains("echo 1")); + assert!(text.contains("echo 2")); + assert!(text.contains("result6")); + assert!(text.find("result2").unwrap() < text.find("result6").unwrap()); + assert_eq!(target.grid().cursor.point.line, Line(0)); + assert_eq!(target.grid()[Line(0)][Column(0)].c, ' '); + } + + #[test] + fn loading_rejects_excess_records_instead_of_growing_on_next_command() { + let mut term = Term::new(Config::default(), &Size, VoidListener); + let mut parser: ansi::Processor = ansi::Processor::new(); + parser.advance(&mut term, b"C:>echo test"); + let mut recent = RecentOutput::default(); + recent.begin(term.grid()); + let record = recent.snapshot(term.grid()).remove(0); + assert!(RecentOutput::try_from_records(vec![record; 6]).is_err()); + } + + #[test] + fn loading_rejects_oversize_records_before_restore() { + let mut term = Term::new(Config::default(), &Size, VoidListener); + let mut parser: ansi::Processor = ansi::Processor::new(); + for _ in 0..200 { + parser.advance(&mut term, b"long unbounded output\r\n"); + } + let snapshot = DisplaySnapshot::capture(term.grid(), Line(-200)..Line(0), 6400); + let record = CommandRecord { captured_at: 0, prompt: snapshot.clone(), output: snapshot }; + assert!(serde_json::to_vec(&record).unwrap().len() > MAX_RECORD_BYTES); + assert!(RecentOutput::try_from_records(vec![record]).is_err()); + } + + #[test] + fn encoded_record_keeps_command_and_tail_within_256_kib() { + let mut term = Term::new(Config::default(), &Size, VoidListener); + let mut parser: ansi::Processor = ansi::Processor::new(); + parser.advance(&mut term, b"C:>large-tool"); + let mut recent = RecentOutput::default(); + recent.begin(term.grid()); + for index in 0..300 { + parser.advance( + &mut term, + format!("\r\n\x1b[38;2;123;234;245mrow{index:03} output\x1b[0m").as_bytes(), + ); + } + let records = recent.snapshot(term.grid()); + let encoded = serde_json::to_vec(&records[0]).unwrap(); + assert!(encoded.len() <= 256 * 1024, "{} encoded bytes", encoded.len()); + let mut target = Term::new(Config::default(), &Size, VoidListener); + RecentOutput::try_from_records(records).unwrap().restore(target.grid_mut()).unwrap(); + let text = target.bounds_to_string( + pebrel_terminal::index::Point::new( + Line(-(target.grid().history_size() as i32)), + Column(0), + ), + pebrel_terminal::index::Point::new(Line(-1), Column(31)), + ); + assert!(text.contains("C:>large-tool")); + assert!(text.contains("row299 output")); + assert!(!text.contains("row000 output")); + } + + #[test] + fn active_output_is_captured_and_two_restores_do_not_duplicate_records() { + let mut term = Term::new(Config::default(), &Size, VoidListener); + let mut parser: ansi::Processor = ansi::Processor::new(); + parser.advance(&mut term, b"C:>tool"); + let mut recent = RecentOutput::default(); + recent.begin(term.grid()); + parser.advance(&mut term, b"\r\npartial"); + let records = recent.snapshot(term.grid()); + assert_eq!(records.len(), 1); + let encoded = serde_json::to_vec(&records).unwrap(); + let restored = + RecentOutput::try_from_records(serde_json::from_slice(&encoded).unwrap()).unwrap(); + let empty = Term::new(Config::default(), &Size, VoidListener); + let encoded_again = serde_json::to_vec(&restored.snapshot(empty.grid())).unwrap(); + assert_eq!(encoded_again, encoded); + } +} diff --git a/pebrel_app/src/recent_output/storage.rs b/pebrel_app/src/recent_output/storage.rs new file mode 100644 index 000000000..54ee02bcf --- /dev/null +++ b/pebrel_app/src/recent_output/storage.rs @@ -0,0 +1,276 @@ +//! 本机 sidecar 编解码边界;调用方拥有保存顺序和清除代次。 + +use std::collections::BTreeMap; +use std::io::{self, Read, Write}; +use std::path::Path; + +use serde::{Deserialize, Serialize}; + +use super::CommandRecord; + +pub(crate) const MAX_STORE_BYTES: usize = 16 * 1024 * 1024; +const MAX_PANES: usize = 4096; +const MAX_TRANSACTION_BYTES: usize = 2 * MAX_STORE_BYTES; + +pub(crate) fn archive_path() -> std::path::PathBuf { + crate::display::nebula_data_dir().join("command-output.json") +} + +#[derive(Clone, Debug, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub(crate) struct Archive { + version: u32, + #[serde(deserialize_with = "decode::panes")] + panes: BTreeMap>, + #[serde( + default, + deserialize_with = "decode::previous", + skip_serializing_if = "Option::is_none" + )] + previous: Option>, +} + +impl Archive { + pub(crate) fn new(panes: BTreeMap>) -> Self { + Self { version: 1, panes, previous: None } + } + + pub(crate) fn take_records(&mut self, id: &str) -> Option> { + self.panes.remove(id).or_else(|| self.previous.as_mut()?.take_records(id)) + } + + fn validate(&self) -> io::Result<()> { + if self.version != 1 || self.panes.len() > MAX_PANES { + return Err(invalid("unsupported or oversized output archive")); + } + for (id, records) in &self.panes { + if !valid_pane_id(id) { + return Err(invalid("invalid pane reference")); + } + super::RecentOutput::validate_records(records).map_err(invalid)?; + } + Ok(()) + } + + fn encode(&self) -> io::Result> { + self.validate()?; + if let Some(previous) = &self.previous { + if previous.previous.is_some() { + return Err(invalid("nested output transaction")); + } + // 两代各自仍受正常上限约束,不能用交接额度保存一份过大的快照。 + previous.encode()?; + Self::new(self.panes.clone()).encode()?; + } + let limit = if self.previous.is_some() { MAX_TRANSACTION_BYTES } else { MAX_STORE_BYTES }; + let mut encoded = LimitedBuffer { bytes: Vec::new(), limit }; + serde_json::to_writer(&mut encoded, self).map_err(io::Error::other)?; + Ok(encoded.bytes) + } + + pub(crate) fn write_to(&self, path: &Path) -> io::Result<()> { + crate::atomic_file::write(path, &self.encode()?) + } + + /// 从中断的两代交接中只保留已发布会话实际引用的记录。 + fn retain_references(&mut self, references: &[String]) { + let mut panes = BTreeMap::new(); + for id in references { + if let Some(records) = self.take_records(id) { + panes.insert(id.clone(), records); + } + } + *self = Self::new(panes); + } + + pub(crate) fn read_from(path: &Path) -> io::Result { + let file = std::fs::File::open(path)?; + if file.metadata()?.len() > MAX_TRANSACTION_BYTES as u64 { + return Err(invalid("output archive exceeds byte budget")); + } + // metadata 之后仍可能增长,读取也必须限流。 + let mut bytes = Vec::new(); + file.take(MAX_TRANSACTION_BYTES as u64 + 1).read_to_end(&mut bytes)?; + if bytes.len() > MAX_TRANSACTION_BYTES { + return Err(invalid("output archive exceeds byte budget")); + } + let archive: Self = serde_json::from_slice(&bytes).map_err(invalid)?; + // 普通文件不能借助读入上限突破 16 MiB;交接文件逐代复核。 + if archive.previous.is_none() && bytes.len() > MAX_STORE_BYTES { + return Err(invalid("output archive exceeds byte budget")); + } + archive.encode().map_err(invalid)?; + Ok(archive) + } +} + +fn valid_pane_id(id: &str) -> bool { + !id.is_empty() && id.len() <= 128 && id.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-') +} + +fn invalid(message: impl std::fmt::Display) -> io::Error { + io::Error::new(io::ErrorKind::InvalidData, message.to_string()) +} + +struct LimitedBuffer { + bytes: Vec, + limit: usize, +} + +impl Write for LimitedBuffer { + fn write(&mut self, bytes: &[u8]) -> io::Result { + if bytes.len() > self.limit.saturating_sub(self.bytes.len()) { + return Err(invalid("output archive exceeds byte budget")); + } + self.bytes.extend_from_slice(bytes); + Ok(bytes.len()) + } + + fn flush(&mut self) -> io::Result<()> { + Ok(()) + } +} + +mod decode; +mod lifecycle; +pub(crate) use lifecycle::OutputStore; + +#[cfg(test)] +mod tests { + use super::*; + use crate::recent_output::{RecentOutput, tests::Size}; + use pebrel_terminal::event::VoidListener; + use pebrel_terminal::term::{Config, Term}; + use pebrel_terminal::vte::ansi; + + pub(super) fn records(command: &str) -> Vec { + let mut term = Term::new(Config::default(), &Size, VoidListener); + let mut parser: ansi::Processor = ansi::Processor::new(); + parser.advance(&mut term, command.as_bytes()); + let mut recent = RecentOutput::default(); + recent.begin(term.grid()); + parser.advance(&mut term, b"\r\nresult\r\n"); + recent.finish(term.grid()); + let mut records = recent.snapshot(term.grid()); + for record in &mut records { + record.captured_at = 0; + } + records + } + + #[test] + fn atomic_round_trip_keeps_same_directory_panes_separate() { + let directory = tempfile::tempdir().unwrap(); + let path = directory.path().join("outputs.json"); + let archive = Archive::new(BTreeMap::from([ + ("pane-one".into(), records("C:>echo one")), + ("pane-two".into(), records("C:>echo two")), + ])); + archive.write_to(&path).unwrap(); + let loaded = Archive::read_from(&path).unwrap(); + assert_eq!(loaded.panes.len(), 2); + assert_eq!(serde_json::to_value(loaded).unwrap(), serde_json::to_value(archive).unwrap()); + } + + #[test] + fn restore_resolves_exact_identity_once_and_never_falls_back_to_another_pane() { + let mut archive = Archive::new(BTreeMap::from([ + ("pane-one".into(), records("C:>echo one")), + ("pane-two".into(), records("C:>echo two")), + ])); + assert!(archive.take_records("missing").is_none()); + let one = archive.take_records("pane-one").unwrap(); + assert!(archive.take_records("pane-one").is_none()); + assert_eq!( + serde_json::to_value(one).unwrap(), + serde_json::to_value(records("C:>echo one")).unwrap() + ); + assert!(archive.take_records("pane-two").is_some()); + } + + #[test] + fn invalid_write_does_not_replace_last_good_archive() { + let directory = tempfile::tempdir().unwrap(); + let path = directory.path().join("outputs.json"); + let mut archive = Archive::new(BTreeMap::from([("pane".into(), records("C:>good"))])); + archive.write_to(&path).unwrap(); + let before = std::fs::read(&path).unwrap(); + archive.version = 999; + assert!(archive.write_to(&path).is_err()); + assert_eq!(std::fs::read(path).unwrap(), before); + } + + #[test] + fn transaction_cannot_hide_oversized_generation_or_nested_transactions() { + let directory = tempfile::tempdir().unwrap(); + let path = directory.path().join("outputs.json"); + let record = records("C:>safe"); + let bytes = serde_json::to_vec(&record).unwrap().len(); + let oversized = Archive::new( + (0..(17 * 1024 * 1024 / bytes)) + .map(|index| (format!("pane-{index}"), record.clone())) + .collect(), + ); + let mut transaction = Archive::new(BTreeMap::new()); + transaction.previous = Some(Box::new(oversized)); + std::fs::write(&path, serde_json::to_vec(&transaction).unwrap()).unwrap(); + assert!(Archive::read_from(&path).is_err()); + assert!(transaction.write_to(&path).is_err()); + let mut nested = Archive::new(BTreeMap::new()); + nested.previous = Some(Box::new(Archive::new(BTreeMap::new()))); + transaction.previous = Some(Box::new(nested)); + std::fs::write(&path, serde_json::to_vec(&transaction).unwrap()).unwrap(); + assert!(Archive::read_from(&path).is_err()); + let oversized = std::fs::File::create(&path).unwrap(); + oversized.set_len(MAX_TRANSACTION_BYTES as u64 + 1).unwrap(); + drop(oversized); + assert!(Archive::read_from(&path).is_err()); + } + + #[test] + fn archive_decoder_checks_pane_and_record_limits_before_materializing_the_next_value() { + let entries = (0..MAX_PANES).map(|i| format!(r#""pane-{i}":[]"#)).collect::>(); + let prefix = format!(r#"{{"version":1,"panes":{{{}"#, entries.join(",")); + let full = format!("{prefix}}}}}"); + let archive: Archive = serde_json::from_str(&full).unwrap(); + assert_eq!(archive.panes.len(), MAX_PANES); + let extra = format!(r#"{prefix},"extra":false}}}}"#); + let error = serde_json::from_str::(&extra).unwrap_err(); + assert!(error.to_string().contains("too many panes"), "{error}"); + + let record = serde_json::to_string(&records("C:>test").remove(0)).unwrap(); + let mut values = vec![record; super::super::MAX_RECORDS]; + values.push("false".into()); + let full = format!(r#"{{"version":1,"panes":{{"pane":[{}]}}}}"#, values.join(",")); + let error = serde_json::from_str::(&full).unwrap_err(); + assert!(error.to_string().contains("too many command records"), "{error}"); + } + + #[test] + fn previous_generation_accepts_null_and_duplicate_pane_ids_are_rejected() { + let json = r#"{"previous":{"previous":null,"panes":{"earlier":[]},"version":1},"panes":{},"version":1}"#; + let mut archive: Archive = serde_json::from_str(json).unwrap(); + assert!(archive.take_records("earlier").is_some()); + let duplicate = r#"{"version":1,"panes":{"same":[],"same":[]}}"#; + let error = serde_json::from_str::(duplicate).unwrap_err(); + assert!(error.to_string().contains("duplicate pane reference"), "{error}"); + } + + #[test] + fn malformed_version_oversize_and_excess_records_are_rejected() { + let directory = tempfile::tempdir().unwrap(); + let path = directory.path().join("outputs.json"); + for contents in [b"broken".as_slice(), b"{\"version\":2,\"panes\":{}}"] { + std::fs::write(&path, contents).unwrap(); + assert!(Archive::read_from(&path).is_err()); + } + let oversized = std::fs::File::create(&path).unwrap(); + oversized.set_len(MAX_STORE_BYTES as u64 + 1).unwrap(); + drop(oversized); + assert!(Archive::read_from(&path).is_err()); + let record = records("C:>test").remove(0); + let archive = Archive::new(BTreeMap::from([("pane".into(), vec![record; 6])])); + std::fs::write(&path, serde_json::to_vec(&archive).unwrap()).unwrap(); + assert!(Archive::read_from(&path).is_err()); + } +} diff --git a/pebrel_app/src/recent_output/storage/decode.rs b/pebrel_app/src/recent_output/storage/decode.rs new file mode 100644 index 000000000..33d04a373 --- /dev/null +++ b/pebrel_app/src/recent_output/storage/decode.rs @@ -0,0 +1,88 @@ +//! Enforce archive cardinality while visiting the on-disk map and record arrays. +use std::collections::BTreeMap; +use std::fmt; + +use serde::de::{Error as _, IgnoredAny, MapAccess, SeqAccess, Visitor}; +use serde::{Deserialize, Deserializer}; + +use super::{Archive, CommandRecord, MAX_PANES, valid_pane_id}; +use crate::recent_output::{MAX_RECORDS, RecentOutput}; + +type Panes = BTreeMap>; + +pub(super) fn panes<'de, D: Deserializer<'de>>(deserializer: D) -> Result { + struct PaneMap; + + impl<'de> Visitor<'de> for PaneMap { + type Value = Panes; + + fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("a map of pane IDs to recent command records") + } + + fn visit_map>(self, mut map: A) -> Result { + let mut panes = Panes::new(); + while let Some(id) = map.next_key::()? { + if panes.len() == MAX_PANES { + return Err(A::Error::custom("too many panes in output archive")); + } + if !valid_pane_id(&id) || panes.contains_key(&id) { + return Err(A::Error::custom("invalid or duplicate pane reference")); + } + let records: Records = map.next_value()?; + panes.insert(id, records.0); + } + Ok(panes) + } + } + deserializer.deserialize_map(PaneMap) +} + +#[derive(Deserialize)] +struct Records(#[serde(deserialize_with = "records")] Vec); + +fn records<'de, D: Deserializer<'de>>(deserializer: D) -> Result, D::Error> { + struct RecordList; + + impl<'de> Visitor<'de> for RecordList { + type Value = Vec; + + fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("a bounded list of recent command records") + } + + fn visit_seq>(self, mut seq: A) -> Result { + let mut records = Vec::new(); + while records.len() < MAX_RECORDS { + let Some(record) = seq.next_element()? else { return Ok(records) }; + RecentOutput::validate_records(std::slice::from_ref(&record)) + .map_err(A::Error::custom)?; + records.push(record); + } + if seq.next_element::()?.is_some() { + return Err(A::Error::custom("too many command records")); + } + Ok(records) + } + } + deserializer.deserialize_seq(RecordList) +} + +pub(super) fn previous<'de, D: Deserializer<'de>>( + deserializer: D, +) -> Result>, D::Error> { + #[derive(Deserialize)] + #[serde(deny_unknown_fields)] + struct Previous { + version: u32, + #[serde(deserialize_with = "panes")] + panes: Panes, + // Older JSON can spell the absent generation as an explicit null. + #[serde(default, rename = "previous")] + _end: (), + } + + Ok(Option::::deserialize(deserializer)?.map(|generation| { + Box::new(Archive { version: generation.version, panes: generation.panes, previous: None }) + })) +} diff --git a/pebrel_app/src/recent_output/storage/lifecycle.rs b/pebrel_app/src/recent_output/storage/lifecycle.rs new file mode 100644 index 000000000..08b83dfd9 --- /dev/null +++ b/pebrel_app/src/recent_output/storage/lifecycle.rs @@ -0,0 +1,494 @@ +//! 后台串行文件操作;UI 仅递增代次,不持有磁盘 I/O 锁。 + +use std::io; +use std::path::PathBuf; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::{Arc, Mutex}; + +use super::Archive; + +#[derive(Clone)] +pub(crate) struct OutputStore { + inner: Arc, +} + +struct StoreState { + path: PathBuf, + generation: AtomicU64, + writer: Mutex<()>, +} + +impl OutputStore { + pub(crate) fn new(path: PathBuf) -> Self { + Self { + inner: Arc::new(StoreState { + path, + generation: AtomicU64::new(0), + writer: Mutex::new(()), + }), + } + } + + pub(crate) fn next_generation(&self) -> u64 { + self.inner.generation.fetch_add(1, Ordering::SeqCst) + 1 + } + + /// 仅由后台执行器调用;返回 false 表示快照已被更新或清除取代。 + pub(crate) fn save(&self, generation: u64, archive: &Archive) -> io::Result { + self.with_generation(generation, || archive.write_to(&self.inner.path)) + } + + /// 后台保存 sidecar 后再发布本机会话引用;发布失败保留上一份有效输出。 + pub(crate) fn save_and_publish( + &self, + generation: u64, + archive: &Archive, + publish: impl FnOnce() -> io::Result<()>, + ) -> io::Result { + self.save_referenced(generation, archive, None, publish) + } + + /// Once publish succeeds, report a committed session even if invalidated inside + /// the callback; the next serialized checkpoint reconciles the new generation. + pub(crate) fn save_referenced( + &self, + generation: u64, + archive: &Archive, + references: Option<&[String]>, + publish: impl FnOnce() -> io::Result<()>, + ) -> io::Result { + let _writer = + self.inner.writer.lock().map_err(|_| io::Error::other("output writer poisoned"))?; + if generation != self.inner.generation.load(Ordering::SeqCst) { + return Ok(false); + } + // A successful callback has already published the session on disk. A later + // generation may schedule a follow-up, but cannot undo that publication. + // Keep both generations until the follow-up has finished. + // 新快照先校验,绝不因为旧文件损坏而接受无效的新内容。 + archive.encode()?; + let mut previous = match Archive::read_from(&self.inner.path) { + Ok(archive) => Some(archive), + Err(error) if error.kind() == io::ErrorKind::NotFound => None, + Err(error) if error.kind() == io::ErrorKind::InvalidData => { + log::warn!("Ignoring invalid command output archive: {error}"); + None + }, + Err(error) => return Err(error), + }; + // 引用必须标识不可变快照,提交期间两代同时可读。进程在发布前 + // 退出时旧 session 仍有效,发布后退出时新 session 也有效。 + if let Some(previous) = &mut previous { + if previous.previous.is_some() { + let references = references.ok_or_else(|| { + io::Error::new( + io::ErrorKind::InvalidData, + "interrupted output publication requires session references", + ) + })?; + previous.retain_references(references); + } + } + let mut staged = archive.clone(); + for (id, records) in &archive.panes { + if let Some(old) = previous.as_ref().and_then(|previous| previous.panes.get(id)) + && serde_json::to_vec(old)? != serde_json::to_vec(records)? + { + return Err(io::Error::new( + io::ErrorKind::InvalidData, + "output reference reused for different data", + )); + } + } + staged.previous = previous.clone().map(Box::new); + staged.write_to(&self.inner.path)?; + if generation != self.inner.generation.load(Ordering::SeqCst) { + return self.restore_previous(previous.as_ref()).map(|()| false); + } + if let Err(error) = publish() { + self.restore_previous(previous.as_ref()).map_err(|rollback| { + io::Error::other(format!( + "session publish failed: {error}; output rollback failed: {rollback}" + )) + })?; + return Err(error); + } + // 发布已成功,压缩失败不回滚引用;旧数据留到下一次成功提交清理。 + if generation == self.inner.generation.load(Ordering::SeqCst) { + if let Err(error) = archive.write_to(&self.inner.path) { + log::warn!("Could not prune previous command output: {error}"); + } + } + Ok(true) + } + + /// Publish a reference-free session without treating a settings toggle as clear. + pub(crate) fn publish_without_output( + &self, + generation: u64, + publish: impl FnOnce() -> io::Result<()>, + ) -> io::Result { + let _writer = + self.inner.writer.lock().map_err(|_| io::Error::other("output writer poisoned"))?; + if generation != self.inner.generation.load(Ordering::SeqCst) { + return Ok(false); + } + publish()?; + Ok(true) + } + + fn restore_previous(&self, previous: Option<&Archive>) -> io::Result<()> { + match previous { + Some(archive) => archive.write_to(&self.inner.path), + None => std::fs::remove_file(&self.inner.path), + } + } + + /// 清除完成后旧写入不能重新出现;调用方须等待结果再显示成功。 + pub(crate) fn clear(&self, generation: u64) -> io::Result { + self.with_generation(generation, || match std::fs::remove_file(&self.inner.path) { + Ok(()) => Ok(()), + Err(error) if error.kind() == io::ErrorKind::NotFound => Ok(()), + Err(error) => Err(error), + }) + } + + fn with_generation( + &self, + generation: u64, + operation: impl FnOnce() -> io::Result<()>, + ) -> io::Result { + let _writer = + self.inner.writer.lock().map_err(|_| io::Error::other("output writer poisoned"))?; + if generation != self.inner.generation.load(Ordering::SeqCst) { + return Ok(false); + } + operation()?; + // UI 可在 I/O 中使代次失效;后续清除在同一锁之后执行。 + Ok(generation == self.inner.generation.load(Ordering::SeqCst)) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::recent_output::storage::{Archive, tests::records}; + use std::collections::BTreeMap; + + fn store_fixture() -> (tempfile::TempDir, PathBuf, OutputStore) { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("outputs.json"); + let store = OutputStore::new(path.clone()); + (dir, path, store) + } + + fn archive(id: &str) -> Archive { + Archive::new(BTreeMap::from([(id.into(), records("C:>echo safe"))])) + } + + #[test] + fn regression_corrupt_archive_does_not_block_new_session_publication() { + let (_dir, path, store) = store_fixture(); + std::fs::write(&path, b"{broken archive").unwrap(); + let published = std::cell::Cell::new(false); + assert!( + store + .save_and_publish(store.next_generation(), &archive("new"), || { + published.set(true); + Ok(()) + }) + .unwrap() + ); + assert!(published.get()); + assert!(Archive::read_from(&path).unwrap().panes.contains_key("new")); + } + + #[test] + fn regression_two_valid_large_generations_do_not_block_publication() { + let (_dir, path, store) = store_fixture(); + let records = records("C:>echo safe"); + let entry_bytes = serde_json::to_vec(&records).unwrap().len(); + let count = 9 * 1024 * 1024 / entry_bytes; + let large = |prefix: &str| { + Archive::new( + (0..count).map(|index| (format!("{prefix}-{index}"), records.clone())).collect(), + ) + }; + let previous = large("previous"); + let next = large("next"); + previous.write_to(&path).unwrap(); + let old_len = std::fs::metadata(&path).unwrap().len(); + assert!(old_len > 8 * 1024 * 1024 && old_len < 16 * 1024 * 1024); + assert!( + store + .save_and_publish(store.next_generation(), &next, || { + let staged = Archive::read_from(&path)?; + let mut staged = staged; + assert!(staged.take_records("previous-0").is_some()); + assert!(staged.take_records("next-0").is_some()); + Ok(()) + }) + .unwrap() + ); + let restored = Archive::read_from(&path).unwrap(); + assert!(restored.panes.contains_key("next-0")); + assert!(!restored.panes.contains_key("previous-0")); + } + + #[test] + fn interrupted_publication_keeps_only_referenced_generation_on_retry() { + for reference in ["previous", "next"] { + let (_dir, path, store) = store_fixture(); + let mut interrupted = archive("next"); + interrupted.previous = Some(Box::new(archive("previous"))); + interrupted.write_to(&path).unwrap(); + let references = vec![reference.to_string()]; + assert!( + store + .save_referenced( + store.next_generation(), + &archive("third"), + Some(&references), + || { + let mut during = Archive::read_from(&path)?; + assert!(during.take_records(reference).is_some()); + assert!(during.take_records("third").is_some()); + let unreferenced = + if reference == "previous" { "next" } else { "previous" }; + assert!(during.take_records(unreferenced).is_none()); + Ok(()) + } + ) + .unwrap() + ); + let after = Archive::read_from(&path).unwrap(); + assert!(after.previous.is_none()); + assert_eq!(after.panes.len(), 1); + } + } + + #[test] + fn interrupted_publication_failed_retry_preserves_referenced_output() { + let (_dir, path, store) = store_fixture(); + let mut interrupted = archive("next"); + interrupted.previous = Some(Box::new(archive("previous"))); + interrupted.write_to(&path).unwrap(); + assert!( + store + .save_referenced( + store.next_generation(), + &archive("third"), + Some(&["previous".into()]), + || { Err(io::Error::other("publication failed")) } + ) + .is_err() + ); + let mut after = Archive::read_from(&path).unwrap(); + assert!(after.take_records("previous").is_some()); + assert!(after.take_records("third").is_none()); + } + + #[test] + fn delayed_save_cannot_resurrect_cleared_output() { + let (_dir, path, store) = store_fixture(); + let old = store.next_generation(); + let clear = store.next_generation(); + store.clear(clear).unwrap(); + assert!(!store.save(old, &archive("old")).unwrap()); + assert!(!path.exists()); + let new = store.next_generation(); + assert!(store.save(new, &archive("new")).unwrap()); + assert!(Archive::read_from(&path).unwrap().panes.contains_key("new")); + } + + #[test] + fn out_of_order_save_cannot_reintroduce_closed_pane() { + let (_dir, path, store) = store_fixture(); + let old = store.next_generation(); + let new = store.next_generation(); + store.save(new, &archive("remaining")).unwrap(); + assert!(!store.save(old, &archive("closed")).unwrap()); + let archive = Archive::read_from(&path).unwrap(); + assert_eq!(archive.panes.len(), 1); + assert!(archive.panes.contains_key("remaining")); + } + + #[test] + fn checkpoint_publishes_references_only_after_output_is_durable() { + let (_dir, path, store) = store_fixture(); + let generation = store.next_generation(); + let published = std::cell::Cell::new(false); + assert!( + store + .save_and_publish(generation, &archive("new"), || { + assert!(Archive::read_from(&path)?.panes.contains_key("new")); + published.set(true); + Ok(()) + }) + .unwrap() + ); + assert!(published.get()); + assert!( + !store + .save_and_publish(generation - 1, &archive("stale"), || { + panic!("stale checkpoint must not publish session references") + }) + .unwrap() + ); + } + + #[test] + fn previous_references_remain_readable_until_new_session_is_published() { + let (_dir, path, store) = store_fixture(); + store.save(store.next_generation(), &archive("previous")).unwrap(); + let next = store.next_generation(); + store + .save_and_publish(next, &archive("new"), || { + let mut during = Archive::read_from(&path)?; + assert!( + during.take_records("previous").is_some(), + "old session must survive a crash before publication" + ); + assert!(during.panes.contains_key("new")); + Ok(()) + }) + .unwrap(); + let after = Archive::read_from(&path).unwrap(); + assert!(after.panes.contains_key("new")); + assert!(!after.panes.contains_key("previous")); + } + + #[test] + fn failed_session_publication_restores_previous_output_archive() { + let (_dir, path, store) = store_fixture(); + let old = store.next_generation(); + store.save(old, &archive("previous")).unwrap(); + let before = std::fs::read(&path).unwrap(); + let next = store.next_generation(); + assert!( + store + .save_and_publish(next, &archive("new"), || { + Err(io::Error::other("session write failed")) + }) + .is_err() + ); + assert_eq!(std::fs::read(&path).unwrap(), before); + assert!(store.save_and_publish(next, &archive("new"), || Ok(())).unwrap()); + } + + #[test] + fn reusing_reference_for_different_output_does_not_overwrite_previous_data() { + let (_dir, path, store) = store_fixture(); + store.save(store.next_generation(), &archive("same-id")).unwrap(); + let before = std::fs::read(&path).unwrap(); + let changed = + Archive::new(BTreeMap::from([("same-id".into(), records("C:>different command"))])); + assert!( + store + .save_and_publish(store.next_generation(), &changed, || { + panic!("a conflicting identity must never be published") + }) + .is_err() + ); + assert_eq!(std::fs::read(path).unwrap(), before); + } + + #[test] + fn invalidation_during_publication_is_acknowledged_before_later_clear() { + let (_dir, path, store) = store_fixture(); + let generation = store.next_generation(); + let clear = std::cell::Cell::new(0); + assert!( + store + .save_and_publish(generation, &archive("new"), || { + clear.set(store.next_generation()); + Ok(()) + }) + .unwrap() + ); + assert!(store.clear(clear.get()).unwrap()); + assert!(!store.save(generation, &archive("new")).unwrap()); + assert!(!path.exists()); + } + + #[test] + fn invalidation_inside_publication_reports_durable_session_and_keeps_old_reference() { + let (dir, path, store) = store_fixture(); + let session_path = dir.path().join("session.json"); + archive("old").write_to(&path).unwrap(); + std::fs::write(&session_path, "old").unwrap(); + let generation = store.next_generation(); + let published = store + .save_referenced(generation, &archive("new"), Some(&["old".into()]), || { + std::fs::write(&session_path, "new")?; + store.next_generation(); + Ok(()) + }) + .unwrap(); + assert!(published, "a written session cannot be reported as cancelled"); + assert_eq!(std::fs::read_to_string(&session_path).unwrap(), "new"); + let mut staged = Archive::read_from(&path).unwrap(); + assert!(staged.take_records("old").is_some()); + assert!(staged.take_records("new").is_some()); + } + + #[test] + fn reference_free_checkpoint_preserves_old_archive_on_failure_and_retry() { + let (dir, path, store) = store_fixture(); + let session_path = dir.path().join("session.json"); + archive("old").write_to(&path).unwrap(); + let generation = store.next_generation(); + assert!( + store + .publish_without_output(generation, || Err(io::Error::other("session unavailable"))) + .is_err() + ); + assert!(!session_path.exists()); + let before = std::fs::read(&path).unwrap(); + assert!( + store + .publish_without_output(generation, || std::fs::write(&session_path, "no refs")) + .unwrap() + ); + assert_eq!(std::fs::read(&path).unwrap(), before); + assert_eq!(std::fs::read_to_string(&session_path).unwrap(), "no refs"); + } + + #[test] + fn clear_queued_during_publication_runs_after_it_and_stays_cleared() { + let (_dir, path, ref store) = store_fixture(); + let old = store.next_generation(); + let (entered, resume) = (std::sync::Barrier::new(2), std::sync::Barrier::new(2)); + std::thread::scope(|scope| { + let first = scope.spawn(|| { + store.save_and_publish(old, &archive("old"), || { + entered.wait(); + resume.wait(); + Ok(()) + }) + }); + entered.wait(); + // The UI invalidates without taking the disk writer lock. + let clear = store.next_generation(); + let second = scope.spawn(move || store.clear(clear)); + resume.wait(); + assert!(first.join().unwrap().unwrap(), "published session is durable"); + assert!(second.join().unwrap().unwrap()); + }); + assert!(!path.exists()); + assert!(!store.save(old, &archive("old")).unwrap()); + } + + #[test] + fn failed_save_preserves_previous_archive_and_allows_retry() { + let (_dir, path, store) = store_fixture(); + let first = store.next_generation(); + store.save(first, &archive("before")).unwrap(); + let next = store.next_generation(); + let mut invalid = archive("after"); + invalid.version = 999; + assert!(store.save(next, &invalid).is_err()); + assert!(Archive::read_from(&path).unwrap().panes.contains_key("before")); + assert!(store.save(next, &archive("after")).unwrap()); + } +}