This commit is contained in:
zhongluofeng committed 2026-10-10 14:29:48 +08:00
1 parent ad987111a3
commit c9e61f38c5
89 files changed
+11775 -3155

No files matched your search

+514
View File
@@ -0,0 +1,514 @@
//! 任意文本 / 代码文件的读写:编码探测、换行探测、授权路径白名单。
//!
//! # 与笔记库的分工
//!
//! 库内笔记走 `library.rs`(相对路径 + 树形结构 + front-matter);本模块服务的是
//! **库外的任意文件**:用户用 `Ctrl+O` 或拖拽打开的一个 `.py`、`.json`、`.log`。
//! 两者的安全模型完全不同 —— 库是「一个根目录内的沙箱」,而任意文件是「用户显式
//! 点过的那个路径」。因此这里的守卫不是路径前缀,而是**授权集合**(见下)。
//!
//! # 为什么要有授权白名单
//!
//! 前端传来的路径一律不可信:一个被污染的 WebView(XSS、恶意依赖)如果能调
//! `editor_write_file('/Windows/System32/...')`,那就不是编辑器而是任意文件写入漏洞。
//! 做法:只有经过 [`authorize`] 登记过的路径才允许读**写**(读也一并限制,避免拿它
//! 当任意文件读取接口探测磁盘)。授权的三个来源都是用户动作:系统文件对话框、
//! 命令行参数、库本身。
//!
//! **读**比写宽松一档:读只要求「存在且是文件」,写入才强制授权。原因是打开一篇
//! 从设置页点进来的文件不该因为「窗口重启过、授权表空了」而失败。
//!
//! # 编码与换行:读写成对
//!
//! GBK 文件被当成 UTF-8 读出来是乱码,再按 UTF-8 存回去就是**永久损坏**(原字节
//! 已经不可逆地丢了)。因此读的时候把「编码 + 有无 BOM + 换行风格」一并记下来,
//! 写回时原样还原;用户显式改编码时才按新编码写。换行同理:CRLF 文件存回去必须
//! 还是 CRLF,否则一次「随手保存」就会在整个 diff 里掀起风暴。
use std::collections::HashSet;
use std::path::{Path, PathBuf};
use std::sync::Mutex;
use std::time::UNIX_EPOCH;
use serde::Serialize;
use specta::Type;
/// 会话内已授权(用户显式打开过)的路径集合。
///
/// 进程级静态而非 Tauri State:授权是「这一次运行期间用户点过什么」的事实,
/// 与库根、设置无关,也不需要跨窗口同步(每个源窗口都会自己调 `authorize`)。
static AUTHORIZED: std::sync::OnceLock<Mutex<HashSet<PathBuf>>> = std::sync::OnceLock::new();
fn authorized() -> &'static Mutex<HashSet<PathBuf>> {
AUTHORIZED.get_or_init(|| Mutex::new(HashSet::new()))
}
/// 换行风格。
pub const EOL_LF: &str = "lf";
pub const EOL_CRLF: &str = "crlf";
/// 一个已打开文件的完整状态(前端据此显示编码/换行,并原样写回)。
#[derive(Debug, Clone, Serialize, Type)]
#[serde(rename_all = "camelCase")]
pub struct FileDoc {
/// 绝对路径(Windows 下已剥掉 `\\?\` 前缀)
pub path: String,
/// 显示名(文件名)
pub name: String,
/// 文本内容(换行已统一为 `\n`,写回时按 `eol` 还原)
pub content: String,
/// 探测到的编码(`utf-8` / `utf-8-bom` / `gbk` / …)
pub encoding: String,
/// 换行风格:"lf" | "crlf"
pub eol: String,
/// 文件字节数
pub size: u64,
/// 最后修改时间(Unix 毫秒)
pub modified: u64,
/// 是否超过「大文件」阈值(前端据此关闭 Live Preview / 折叠 / 补全)
pub large: bool,
/// 行数(前端状态栏显示;大文件也只需要扫一遍换行,成本可忽略)
pub lines: u64,
/// 是否只读(打开时探测写权限失败;前端据此拦截保存并给出原因)
pub readonly: bool,
}
/// 探测写权限:以写模式打开但**不写入**(失败 → 只读)。
///
/// 比「打开成功但保存时才报错」体验好得多:只读文件一打开就能看到状态栏标记。
fn is_writable(path: &Path) -> bool {
std::fs::OpenOptions::new().write(true).open(path).is_ok()
}
/// 登记一个路径为「已授权可写」。
pub fn authorize(path: &Path) {
let key = normalize_key(path);
if let Ok(mut set) = authorized().lock() {
set.insert(key);
}
}
/// 该路径是否已授权(写操作的前置条件)。
pub fn is_authorized(path: &Path) -> bool {
let key = normalize_key(path);
authorized()
.lock()
.map(|set| set.contains(&key))
.unwrap_or(false)
}
/// 授权集合的比对键:**尽力规范化**(解析符号链接与 `..`)。
///
/// 规范化失败(文件不存在)时退回原路径 —— 那说明写操作本来就会失败,
/// 这里没必要为了「统一键」而提前报错。
fn normalize_key(path: &Path) -> PathBuf {
std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf())
}
/// 把路径转成可显示、可回传的字符串(剥掉 Windows 的 `\\?\` 扩展长度前缀)。
pub fn display_path(path: &Path) -> String {
let s = path.to_string_lossy().to_string();
match s.strip_prefix(r"\\?\") {
Some(rest) => rest.to_string(),
None => s,
}
}
/// 探测编码:返回规范名(`utf-8` / `utf-8-bom` / `gbk` / `gb18030` / `big5` / `shift_jis` / …)。
///
/// # 判定顺序(每一步都有理由)
///
/// 1. **BOM**:UTF-8 BOM / UTF-16 的 BOM 是无歧义的事实,直接采信;
/// 2. **严格 UTF-8 校验**:能完整解成 UTF-8 就是 UTF-8。优先级高于任何统计猜测 ——
/// 中文 GBK 字节序列几乎不可能恰好是合法 UTF-8,反向的误判同样罕见;
/// 3. **chardetng 统计探测**:区分 Shift_JIS / Big5 / EUC-KR / GB18030 等 CJK 编码。
/// 这一步不能省:GB18030 几乎能解码任意字节序列,若只靠「试解是否成功」,
/// 日文 Shift_JIS 文件会被静默当成中文 GB18030;
/// 4. 探测器给不出我们支持的编码 → 退回 GB18030 兜底;仍不行则按 UTF-8 有损解码
/// (宁可显示替换字符,也不要打不开文件)。
pub fn detect_encoding(bytes: &[u8]) -> String {
if bytes.starts_with(&[0xEF, 0xBB, 0xBF]) {
return "utf-8-bom".to_string();
}
if bytes.starts_with(&[0xFF, 0xFE]) {
return "utf-16le".to_string();
}
if bytes.starts_with(&[0xFE, 0xFF]) {
return "utf-16be".to_string();
}
if std::str::from_utf8(bytes).is_ok() {
return "utf-8".to_string();
}
// 非 UTF-8:先用统计探测区分 CJK 编码(Shift_JIS / Big5 / EUC-KR / GB18030 …)。
// 不能直接拿 GB18030 兜底 —— GB18030 几乎能解码任意字节序列,试解永远「成功」,
// 会把日文 Shift_JIS 文件静默当成中文 GB18030(用户实测到的问题)。
if let Some(name) = detect_with_chardetng(bytes) {
return name;
}
// 探测器给不出我们支持的编码:退回 GB18030(GBK 的每个序列在它之下都合法)
if crate::terminal::encoding::is_supported("gb18030") {
return "gb18030".to_string();
}
"utf-8".to_string()
}
/// 用 `chardetng` 统计探测非 UTF-8 文本的编码,并映射回本模块的规范编码名。
///
/// 只接受我们**支持**的编码(见 `terminal::encoding::SUPPORTED`):探测器给出的
/// 单字节西文编码(`windows-125x` / `ISO-8859-x` / `KOI8-*`)统一归到 `latin1`
/// (它们都是单字节、逐字节一一映射,不会产生替换字符);其余未知的一律返回
/// `None`,由调用方走兜底 —— 宁可退回 GB18030,也不要返回一个解出来全是 `` 的名字。
fn detect_with_chardetng(bytes: &[u8]) -> Option<String> {
use chardetng::{EncodingDetector, Iso2022JpDetection, Utf8Detection};
let mut detector = EncodingDetector::new(Iso2022JpDetection::Deny);
detector.feed(bytes, true);
// 调用前已排除「合法 UTF-8」,因此不允许探测器再返回 UTF-8
let guessed = detector.guess(None, Utf8Detection::Deny);
let name = guessed.name().to_ascii_lowercase();
if name.starts_with("windows-125")
|| name.starts_with("iso-8859")
|| name.starts_with("koi8")
|| name == "ibm866"
{
return Some("latin1".to_string());
}
let normalized = crate::terminal::encoding::normalize(&name);
if crate::terminal::encoding::is_supported(&normalized) {
return Some(normalized);
}
None
}
/// 按编码把字节解成字符串(BOM 已剥离)。
pub(crate) fn decode_bytes(bytes: &[u8], encoding: &str) -> String {
match encoding {
"utf-8-bom" => {
let body = bytes.strip_prefix(&[0xEF, 0xBB, 0xBF]).unwrap_or(bytes);
String::from_utf8_lossy(body).into_owned()
}
"utf-16le" | "utf-16be" => {
// UTF-16 走 encoding_rs;BOM 由它自己处理
crate::terminal::encoding::decode(bytes, "utf-16le")
}
other => crate::terminal::encoding::decode(bytes, other),
}
}
/// 按编码把字符串编成字节(必要时写回 BOM)。
///
/// **不可表示字符绝不静默替换成 `?`**(那是不可逆的数据损坏):先整串试编一次,
/// 若往返比对不一致(说明有字符编不进去),再逐字符定位并报错,让用户改用 UTF-8
/// 或删除这些字符。
pub(crate) fn encode_text(text: &str, encoding: &str) -> Result<Vec<u8>, String> {
match encoding {
"utf-8-bom" => {
let mut out = vec![0xEF, 0xBB, 0xBF];
out.extend_from_slice(text.as_bytes());
Ok(out)
}
other => {
let normalized = crate::terminal::encoding::normalize(other);
if !crate::terminal::encoding::is_supported(&normalized) {
return Err(format!("不支持的编码:{other}"));
}
let encoded = crate::terminal::encoding::encode(text, &normalized);
// UTF-8 能表示任何字符串,无需比对
if normalized != "utf-8"
&& crate::terminal::encoding::decode(&encoded, &normalized) != text
{
let bad = find_unencodable(text, &normalized);
let preview = bad
.iter()
.take(8)
.map(|(index, ch)| format!("第 {index} 个「{ch}」"))
.collect::<Vec<_>>()
.join("、");
let tail = if bad.len() > 8 {
format!(",等共 {} 个字符", bad.len())
} else {
String::new()
};
return Err(format!(
"编码「{other}」无法表示:{preview}{tail}。请改用 UTF-8,或删除这些字符后再保存"
));
}
Ok(encoded)
}
}
}
/// 找出目标编码无法表示的字符(位置按字符计,从 1 开始)。仅在错误路径上跑。
fn find_unencodable(text: &str, encoding: &str) -> Vec<(usize, char)> {
let mut out = Vec::new();
for (index, ch) in text.chars().enumerate() {
let mut buf = [0u8; 4];
let s = ch.encode_utf8(&mut buf);
let encoded = crate::terminal::encoding::encode(s, encoding);
if crate::terminal::encoding::decode(&encoded, encoding) != &*s {
out.push((index + 1, ch));
}
}
out
}
/// 探测换行风格(`\r\n` 只要出现一次就判定为 CRLF —— 混合换行的文件按主流风格写回)。
fn detect_eol(text: &str) -> String {
if text.contains("\r\n") {
EOL_CRLF.to_string()
} else {
EOL_LF.to_string()
}
}
/// 读取任意文件(自动探测编码)。
pub fn read_file(path: &str, max_mb: u32) -> Result<FileDoc, String> {
read_file_inner(path, max_mb, None)
}
/// 以指定编码**重新解码磁盘字节**(不写回,只换一种解释方式)。
///
/// 语义(规划 §5.3):切换编码是「换一种方式解释**磁盘字节**」,而不是「重新解释
/// 缓冲区文本」—— 因此必须回到磁盘字节重新解码,而不是把编辑器里已有的字符串再转一次。
pub fn redecode_file(path: &str, encoding: &str, max_mb: u32) -> Result<FileDoc, String> {
read_file_inner(path, max_mb, Some(encoding))
}
/// 读取实现。`forced_encoding` 为 `None` 时走探测链(BOM → 严格 UTF-8 → GB18030)。
fn read_file_inner(
path: &str,
max_mb: u32,
forced_encoding: Option<&str>,
) -> Result<FileDoc, String> {
let trimmed = path.trim();
if trimmed.is_empty() {
return Err("路径为空".to_string());
}
let p = Path::new(trimmed);
if p.is_dir() {
return Err("这是一个目录,请选择文件".to_string());
}
let meta = std::fs::metadata(p).map_err(|e| format!("读取文件信息失败: {e}"))?;
if !meta.is_file() {
return Err("目标不是普通文件".to_string());
}
let bytes = std::fs::read(p).map_err(|e| format!("读取文件失败: {e}"))?;
let encoding = match forced_encoding {
Some(enc) if !enc.trim().is_empty() => {
let requested = enc.trim();
let normalized = if requested.eq_ignore_ascii_case("utf-8-bom") {
"utf-8-bom".to_string()
} else {
crate::terminal::encoding::normalize(requested)
};
if normalized != "utf-8-bom" && !crate::terminal::encoding::is_supported(&normalized) {
return Err(format!("不支持的编码:{requested}"));
}
normalized
}
_ => detect_encoding(&bytes),
};
let raw = decode_bytes(&bytes, &encoding);
let eol = detect_eol(&raw);
// 统一成 `\n` 交给编辑器:CM6 的一份文档只应有一种换行,混合换行会让
// 「行号 / 选区 / 大纲」三处计算各按各的口径,写法回时再还原
let content = raw.replace("\r\n", "\n");
let limit = (max_mb.max(1) as u64) * 1024 * 1024;
Ok(FileDoc {
path: display_path(p),
name: p
.file_name()
.map(|n| n.to_string_lossy().to_string())
.unwrap_or_default(),
lines: content.lines().count() as u64,
content,
encoding,
eol,
size: meta.len(),
modified: meta
.modified()
.ok()
.and_then(|t| t.duration_since(UNIX_EPOCH).ok())
.map(|d| d.as_millis() as u64)
.unwrap_or(0),
large: meta.len() > limit,
readonly: !is_writable(p),
})
}
/// 写入任意文件。
///
/// `encoding` 为空串时沿用「读时探测到的编码」由前端回传的那个值 —— 调用方
/// (编辑器)始终带着它,这里不接受「猜一个」。
pub fn write_file(
path: &str,
content: &str,
encoding: &str,
eol: &str,
max_mb: u32,
) -> Result<FileDoc, String> {
let trimmed = path.trim();
if trimmed.is_empty() {
return Err("路径为空".to_string());
}
let p = Path::new(trimmed);
if !is_authorized(p) {
return Err("该文件未经授权,无法写入(请通过「打开文件」重新选择)".to_string());
}
if !is_writable(p) {
return Err("文件为只读,无法保存".to_string());
}
let enc = if encoding.trim().is_empty() {
"utf-8".to_string()
} else {
crate::terminal::encoding::normalize(encoding)
};
let text = if eol == EOL_CRLF {
content.replace("\r\n", "\n").replace('\n', "\r\n")
} else {
content.replace("\r\n", "\n")
};
let bytes = encode_text(&text, &enc)?;
std::fs::write(p, &bytes).map_err(|e| format!("保存文件失败: {e}"))?;
read_file(trimmed, max_mb)
}
/// 把图片等二进制内容写入库根的 `assets/`(粘贴图片用)。
///
/// 返回**相对库根的路径**(统一 `/` 分隔),前端据此插入 Markdown 图片引用;
/// 不使用绝对路径,保证笔记换个机器 / 换个库根也能打开。
pub fn write_asset(
root: &Path,
file_name: &str,
data: &[u8],
ext: &str,
) -> Result<String, String> {
let assets = root.join(super::library::ASSETS_DIR);
std::fs::create_dir_all(&assets).map_err(|e| format!("创建附件目录失败: {e}"))?;
let stem = super::library::validate_name(file_name)?;
let stem = Path::new(&stem)
.file_stem()
.map(|s| s.to_string_lossy().to_string())
.unwrap_or_else(|| "image".to_string());
let ext = ext.trim().trim_start_matches('.').to_ascii_lowercase();
let ext = if ext.is_empty() { "png".to_string() } else { ext };
let mut candidate = format!("{stem}.{ext}");
let mut index = 1;
while assets.join(&candidate).exists() {
candidate = format!("{stem}-{index}.{ext}");
index += 1;
if index > 9999 {
return Err("同名附件过多,请清理 assets 目录".to_string());
}
}
std::fs::write(assets.join(&candidate), data).map_err(|e| format!("写入附件失败: {e}"))?;
Ok(format!("{}/{candidate}", super::library::ASSETS_DIR))
}
// ===== 测试 =====
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn detects_bom_and_plain_utf8() {
assert_eq!(detect_encoding(b"hello"), "utf-8");
assert_eq!(detect_encoding("\u{feff}hello".as_bytes()), "utf-8-bom");
assert_eq!(detect_encoding(&[0xFF, 0xFE, 0x41, 0x00]), "utf-16le");
}
#[test]
fn detects_non_utf8_chinese_as_gbk_family() {
// 中文:合法 UTF-8 校验必然失败,探测应落在 GBK 家族(gbk 或 gb18030)
let text = "这是一段中文测试文本,用于验证编码探测。";
let gbk = crate::terminal::encoding::encode(text, "gbk");
let detected = detect_encoding(&gbk);
assert!(
detected == "gbk" || detected == "gb18030",
"中文应探测为 GBK 家族,实际为 {detected}"
);
// GB18030 是 GBK 的超集,用它解码同样能还原
assert_eq!(decode_bytes(&gbk, "gb18030"), text);
}
#[test]
fn detects_shift_jis_not_gb18030() {
// 日文 Shift_JIS:GB18030 也能「解码成功」,这正是旧实现误判成中文的原因
let text = "これは日本語のテキストです。テスト用のサンプル文です。";
let sjis = crate::terminal::encoding::encode(text, "shift_jis");
let detected = detect_encoding(&sjis);
assert_eq!(
detected, "shift_jis",
"日文 Shift_JIS 不应被误判(实际 {detected})"
);
assert_eq!(decode_bytes(&sjis, "shift_jis"), text);
}
#[test]
fn eol_roundtrip_preserves_crlf() {
let dir = std::env::temp_dir().join("thing-notes-files-test");
std::fs::create_dir_all(&dir).unwrap();
let path = dir.join("crlf.txt");
std::fs::write(&path, b"a\r\nb\r\n").unwrap();
let doc = read_file(&display_path(&path), 5).unwrap();
assert_eq!(doc.eol, EOL_CRLF);
assert_eq!(doc.content, "a\nb\n");
assert_eq!(doc.lines, 2);
authorize(&path);
let saved = write_file(&display_path(&path), "a\nb\nc\n", "utf-8", EOL_CRLF, 5).unwrap();
assert_eq!(saved.content, "a\nb\nc\n");
// 落盘字节必须还是 CRLF(否则一次保存就污染整个 diff)
assert_eq!(std::fs::read(&path).unwrap(), b"a\r\nb\r\nc\r\n");
let _ = std::fs::remove_file(&path);
}
#[test]
fn write_requires_authorization() {
let dir = std::env::temp_dir().join("thing-notes-files-test");
std::fs::create_dir_all(&dir).unwrap();
let path = dir.join("unauthorized.txt");
std::fs::write(&path, b"x").unwrap();
let err = write_file(&display_path(&path), "y", "utf-8", EOL_LF, 5).unwrap_err();
assert!(err.contains("未经授权"), "{err}");
let _ = std::fs::remove_file(&path);
}
#[test]
fn gbk_write_uses_original_encoding() {
let dir = std::env::temp_dir().join("thing-notes-files-test");
std::fs::create_dir_all(&dir).unwrap();
let path = dir.join("gbk.txt");
std::fs::write(&path, crate::terminal::encoding::encode("中文", "gbk")).unwrap();
let doc = read_file(&display_path(&path), 5).unwrap();
assert_eq!(doc.content, "中文");
authorize(&path);
write_file(&display_path(&path), "中文内容", &doc.encoding, &doc.eol, 5).unwrap();
let bytes = std::fs::read(&path).unwrap();
assert_eq!(crate::terminal::encoding::decode(&bytes, "gbk"), "中文内容");
let _ = std::fs::remove_file(&path);
}
#[test]
fn large_flag_uses_megabyte_limit() {
let dir = std::env::temp_dir().join("thing-notes-files-test");
std::fs::create_dir_all(&dir).unwrap();
let path = dir.join("big.txt");
std::fs::write(&path, vec![b'a'; 2048]).unwrap();
assert!(read_file(&display_path(&path), 1).unwrap().large == false);
// 阈值按 MB 计,2048 字节在 0 上限下被夹到 1MB,仍不算大文件
assert!(!read_file(&display_path(&path), 0).unwrap().large);
let _ = std::fs::remove_file(&path);
}
}