//! 音乐模块 · 本地解密(`music/decrypt/`)。 //! //! 挂靠音乐模块的「解密」页签,与下载链路同构:命令先回一个 `taskId`, //! 之后所有进度经 `music-decrypt-event` 推送(前端 `decryptStore` 常驻监听, //! 页签切换卸载组件也不影响任务)。 //! //! ## 分工 //! //! - [`ncm`]:网易云 `.ncm` 的**纯 Rust 离线**引擎(P0 全部范围)。 //! - `qq`(P1,未实施):QQ 音乐三层路由(内嵌 ekey 离线 → musicex API → Frida 兜底)。 //! 见 `MUSIC_DECRYPT_PLAN.md` §3.2。 //! - [`commands`]:Tauri 命令层(run / cancel)。 //! //! ## 为什么事件在独立线程里发 //! //! 解密是 CPU + 磁盘密集的同步流程,每读一块就要回报进度。把它放在 //! `spawn_blocking` 里再逐块 `emit` 会阻塞 tokio 的工作线程; //! 这里改为「`std::thread` 干活 + `mpsc` 回传事件 + 异步任务节流转发」, //! 读盘线程最多被 `mpsc::send` 短暂挡住,不碰 tokio 运行时。 //! //! 进度**按时间节流**([`PROGRESS_INTERVAL`]):单个大文件有成千上万个 32KB 块, //! 不节流会把 WebView 的事件通道打满。 pub mod commands; pub mod common; pub mod ncm; pub mod probe; pub mod qmc; pub mod qq_credentials; pub mod qq_ekey; pub mod qq_footer; pub mod qq_online; pub mod scan; /// QQ 音乐进程内存扫描:纯 Win32 实现,非 Windows 平台不编译。 #[cfg(windows)] pub mod qq_memscan; use std::collections::HashMap; use std::path::PathBuf; use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::{mpsc, Arc, Mutex}; use std::time::{Duration, Instant}; use serde::{Deserialize, Serialize}; use specta::Type; use tauri::{AppHandle, Emitter}; use common::DecryptError; /// 进度事件的最小间隔 pub const PROGRESS_INTERVAL: Duration = Duration::from_millis(300); /// 单文件处理结果的三个状态 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Type)] #[serde(rename_all = "lowercase")] pub enum FileStatus { /// 解密成功 Ok, /// 失败(`message` 为可读原因) Error, /// 该文件不属于本平台/本阶段支持范围 Unsupported, } /// 推送给前端的事件负载(与 `src/lib/bindings.ts` / `decryptStore.ts` 对应)。 #[derive(Debug, Clone, Serialize, Deserialize, Type)] #[serde(tag = "type", rename_all = "kebab-case")] pub enum DecryptEvent { /// 批次开始,`total` 为待处理文件数 Start { task_id: String, total: usize }, /// 单个文件处理完毕 File { task_id: String, /// 0-based 序号,与任务表行一一对应 index: usize, name: String, status: FileStatus, /// 失败原因,或成功时的备注(平台 / 密钥形态) message: Option, /// 主产物路径 output: Option, /// 单独落盘的封面(网易云 ncm 带内嵌封面时才有) cover: Option, }, /// 进度(节流后) Progress { task_id: String, done: usize, total: usize, /// 当前文件已处理字节数 / 总字节数(0 表示未知) bytes_done: u64, bytes_total: u64, name: String, }, /// 批次结束 Finished { task_id: String, ok: usize, failed: usize, /// 被取消时尚未处理的文件数 cancelled: usize, }, } /// 任务表条目。只存「是否被要求取消」,不存进度—— /// 进度的权威在前端 store(事件即真相),Rust 侧不需要镜像状态。 pub struct DecryptTasks { inner: Mutex>>, } impl Default for DecryptTasks { fn default() -> Self { Self::new() } } impl DecryptTasks { pub fn new() -> Self { Self { inner: Mutex::new(HashMap::new()), } } /// 登记一个任务并返回它的取消标志 pub fn register(&self, task_id: &str) -> Arc { let flag = Arc::new(AtomicBool::new(false)); if let Ok(mut m) = self.inner.lock() { m.insert(task_id.to_string(), flag.clone()); } flag } /// 请求取消;返回是否命中了一个在跑的任务 pub fn cancel(&self, task_id: &str) -> bool { match self.inner.lock() { Ok(m) => match m.get(task_id) { Some(flag) => { flag.store(true, Ordering::SeqCst); true } None => false, }, Err(_) => false, } } pub fn finish(&self, task_id: &str) { if let Ok(mut m) = self.inner.lock() { m.remove(task_id); } } } /// 线程 → 异步任务的事件通道消息 enum Msg { Progress { bytes_done: u64, bytes_total: u64, name: String, }, File { index: usize, name: String, status: FileStatus, message: Option, output: Option, cover: Option, }, /// 批次结束。**必须走通道**——否则它会在转发线程尚未冲出积压的 /// `File` 事件之前就被 `emit`,前端会先看到"完成"再看到最后几个文件的结果。 Finished { ok: usize, failed: usize, cancelled: usize, }, } /// 该文件是否是「需要联网取密钥」的形态(musicex)。 /// /// 只读尾部 192 字节,代价可忽略;用作"离线失败后要不要转在线"的判据, /// 避免对普通失败(如尾部损坏)也去发起网络请求。 fn needs_online(path: &std::path::Path) -> bool { use std::io::{Read, Seek, SeekFrom}; let Ok(mut f) = std::fs::File::open(path) else { return false; }; let Ok(size) = f.metadata().map(|m| m.len()) else { return false; }; let take = (qq_footer::MUSICEX_FOOTER_LEN as u64).min(size) as usize; if take < 8 || f.seek(SeekFrom::End(-(take as i64))).is_err() { return false; } let mut buf = vec![0u8; take]; if f.read_exact(&mut buf).is_err() { return false; } qq_footer::is_musicex_tail(&buf) } /// 启动一个解密批次:登记任务 → 起工作线程 → 异步转发事件。 /// /// 调用方(`commands::music_decrypt_run`)已完成参数校验与目录扫描;本函数只负责调度。 /// /// `in_place = true` 时**忽略 `out_dir`**,产物与源文件同目录同名(扩展名按格式改)。 /// 这是文件夹批量的默认方式——用户的期望是"就地解出来",而不是去另一个目录找。 pub fn spawn_batch( app: AppHandle, tasks: Arc, task_id: String, files: Vec, out_dir: PathBuf, in_place: bool, ) { let flag = tasks.register(&task_id); let (tx, rx) = mpsc::channel::(); let total_files = files.len(); // ---- 工作线程:逐文件解密 ---- let worker_task_id = task_id.clone(); let worker_tasks = tasks.clone(); std::thread::Builder::new() .name(format!("music-decrypt-{task_id}")) .spawn(move || { let total = files.len(); // 批次内已占用的输出名(防同名互相覆盖,见 common::unique_output) let mut reserved = std::collections::HashSet::new(); let mut ok = 0usize; let mut failed = 0usize; let mut cancelled = 0usize; let mut done = 0usize; for (index, job) in files.iter().enumerate() { if flag.load(Ordering::SeqCst) { cancelled = total - done; break; } // 输出目录:就地模式与源文件同目录;否则按相对目录还原结构 let target_dir = if in_place { job.path .parent() .map(|p| p.to_path_buf()) .unwrap_or_else(|| out_dir.clone()) } else { common::ensure_subdir(&out_dir, job.rel_parent.as_deref()) .unwrap_or_else(|_| out_dir.clone()) }; // 进度回调:只在文件内部回报,节流交给接收端 let tx_progress = tx.clone(); let name = job.name.clone(); // 「网易云 / QQ音乐」前缀由调度层给出——引擎自己不该知道路由结果 let label = job.engine.label(); let mut progress_cb = |bytes_done: u64, bytes_total: u64| { let _ = tx_progress.send(Msg::Progress { bytes_done, bytes_total, name: name.clone(), }); }; let result = match job.engine { scan::Engine::Ncm => ncm::decrypt_file( &job.path, &target_dir, label, &mut reserved, &mut progress_cb, ), // musicex 的 ekey 不在文件里,离线路径会返回明确的 KeyRequired; // 命中该形态时改走「本机凭据 → 在线取密钥」。 scan::Engine::Qmc => { let offline = qmc::decrypt_file( &job.path, &target_dir, label, &mut reserved, &mut progress_cb, ); match offline { Err(DecryptError::KeyRequired(_)) if needs_online(&job.path) => { qq_online::decrypt_musicex( &job.path, &target_dir, label, &mut progress_cb, ) } other => other, } } }; done += 1; match result { Ok(res) => { ok += 1; crate::logger::log_info( "music-decrypt", &format!( "{} → {}({},{} 字节)", job.path.display(), res.output.display(), res.format, res.audio_bytes ), ); let _ = tx.send(Msg::File { index, name: job.name.clone(), status: FileStatus::Ok, // 成功时把备注(平台/密钥形态)与产物一起回报 message: Some(res.note), output: Some(res.output.to_string_lossy().to_string()), cover: res.cover.map(|c| c.to_string_lossy().to_string()), }); } Err(e) => { failed += 1; crate::logger::log_warn( "music-decrypt", &format!("{} 解密失败:{e}", job.path.display()), ); let _ = tx.send(Msg::File { index, name: job.name.clone(), status: FileStatus::Error, message: Some(e.to_string()), output: None, cover: None, }); } } // 文件收尾时必推一次,保证进度条不因节流停在中间 let _ = tx.send(Msg::Progress { bytes_done: done as u64, bytes_total: total as u64, name: job.name.clone(), }); } // 通道关闭 → 接收端读完剩余消息后收尾 let _ = tx.send(Msg::Finished { ok, failed, cancelled, }); drop(tx); worker_tasks.finish(&worker_task_id); }) .expect("无法创建解密工作线程"); // ---- 异步转发:节流 + 顺序保证 ---- // // 语义: // - `File` 事件(含文件收尾的那次 Progress)**立即转发**,否则结果会看起来卡在末尾。 // - 文件内部的逐块 Progress 只保留最新一条,按 [`PROGRESS_INTERVAL`] 最多发一次, // 避免单个大文件的成千上万个块把 WebView 事件通道打满。 tauri::async_runtime::spawn(async move { let mut last_progress: Option = None; let mut last_emit = Instant::now() - PROGRESS_INTERVAL; let mut current_index = 0usize; // 批内文件总数:与下面 Start 事件取同一份来源 let current_total = total_files; // Start 先发:它必须在任何 Progress/File 之前到达,前端据此建行。 let _ = app.emit( crate::constants::events::MUSIC_DECRYPT_EVENT, &DecryptEvent::Start { task_id: task_id.clone(), total: total_files, }, ); loop { // 单次 recv_timeout 同时兼顾「有消息就收」和「到点就 flush」 let msg = match rx.recv_timeout(PROGRESS_INTERVAL) { Ok(m) => Some(m), Err(mpsc::RecvTimeoutError::Timeout) => None, Err(mpsc::RecvTimeoutError::Disconnected) => break, }; match msg { Some(Msg::Progress { bytes_done, bytes_total, name, }) => { // 攒着;下面的 flush 决定何时真正发出 last_progress = Some(Msg::Progress { bytes_done, bytes_total, name, }); } Some(Msg::File { index, name, status, message, output, cover, }) => { // 结果事件优先:先把攒住的进度冲掉,再发结果,保证顺序自然 flush_progress( &app, &task_id, &mut last_progress, &mut last_emit, current_index, current_total, ); let _ = app.emit( crate::constants::events::MUSIC_DECRYPT_EVENT, &DecryptEvent::File { task_id: task_id.clone(), index, name, status, message, output, cover, }, ); current_index = index + 1; } Some(Msg::Finished { ok, failed, cancelled, }) => { // 收尾前把攒住的进度冲掉,再发 Finished,保证前端不丢最后一格进度 last_emit = Instant::now() - PROGRESS_INTERVAL; flush_progress( &app, &task_id, &mut last_progress, &mut last_emit, current_index, current_total, ); let _ = app.emit( crate::constants::events::MUSIC_DECRYPT_EVENT, &DecryptEvent::Finished { task_id: task_id.clone(), ok, failed, cancelled, }, ); // 通道随后关闭,循环自然退出 } None => { /* 超时,走下面的 flush */ } } flush_progress( &app, &task_id, &mut last_progress, &mut last_emit, current_index, current_total, ); } }); } /// 到点则把攒下的最新一条进度发出(最多每 [`PROGRESS_INTERVAL`] 一次)。 fn flush_progress( app: &AppHandle, task_id: &str, pending: &mut Option, last_emit: &mut Instant, index: usize, total: usize, ) { if pending.is_none() || last_emit.elapsed() < PROGRESS_INTERVAL { return; } if let Some(Msg::Progress { bytes_done, bytes_total, name, }) = pending.take() { *last_emit = Instant::now(); let _ = app.emit( crate::constants::events::MUSIC_DECRYPT_EVENT, &DecryptEvent::Progress { task_id: task_id.to_string(), // index = 当前正在处理的文件序号(已完成的文件数) done: index, total, bytes_done, bytes_total, name, }, ); } } #[cfg(test)] mod tests { use super::*; /// **跨端契约**:事件的实际 JSON 形状是前端 `decryptStore.ts` 里 `RawEvent` /// 的镜像。曾经打算写 camelCase(`taskId`),但枚举上只有 `tag` 带了 /// `rename_all`,**字段名仍是 snake_case**——两边不一致时不会编译报错, /// 只会表现为「任务建好了但进度永远不动」。这个测试把形状钉死。 #[test] fn event_json_contract() { let start = serde_json::to_value(DecryptEvent::Start { task_id: "t1".into(), total: 3, }) .unwrap(); assert_eq!( start, serde_json::json!({ "type": "start", "task_id": "t1", "total": 3 }) ); let file = serde_json::to_value(DecryptEvent::File { task_id: "t1".into(), index: 2, name: "a.ncm".into(), status: FileStatus::Error, message: Some("坏了".into()), output: None, cover: None, }) .unwrap(); assert_eq!( file, serde_json::json!({ "type": "file", "task_id": "t1", "index": 2, "name": "a.ncm", "status": "error", "message": "坏了", "output": null, "cover": null }) ); let progress = serde_json::to_value(DecryptEvent::Progress { task_id: "t1".into(), done: 1, total: 3, bytes_done: 10, bytes_total: 100, name: "a.ncm".into(), }) .unwrap(); assert_eq!( progress, serde_json::json!({ "type": "progress", "task_id": "t1", "done": 1, "total": 3, "bytes_done": 10, "bytes_total": 100, "name": "a.ncm" }) ); let finished = serde_json::to_value(DecryptEvent::Finished { task_id: "t1".into(), ok: 2, failed: 1, cancelled: 0, }) .unwrap(); assert_eq!( finished, serde_json::json!({ "type": "finished", "task_id": "t1", "ok": 2, "failed": 1, "cancelled": 0 }) ); } /// `FileStatus` 的三个取值必须是前端 `DecryptFileStatus` 认得的字面量 #[test] fn file_status_variants_are_lowercase() { let j = |s| serde_json::to_string(&s).unwrap(); assert_eq!(j(FileStatus::Ok), "\"ok\""); assert_eq!(j(FileStatus::Error), "\"error\""); assert_eq!(j(FileStatus::Unsupported), "\"unsupported\""); } /// 平台路由见 `scan::route`(内容优先于后缀)——这里只验证单测覆盖到的路径。 #[test] fn engine_route_by_content_and_extension() { use scan::Engine; let dir = std::env::temp_dir().join(format!("dec_route_{}", std::process::id())); let _ = std::fs::remove_dir_all(&dir); std::fs::create_dir_all(&dir).unwrap(); // 网易云:只看魔数,后缀随便 let ncm = dir.join("x.bin"); let mut bytes = b"CTENFDAM".to_vec(); bytes.extend_from_slice(&[0x02, 0x00, 0, 0, 0, 0]); std::fs::write(&ncm, &bytes).unwrap(); assert_eq!(scan::route(&ncm), Some(Engine::Ncm)); // QQ:后缀在家族里 let qmc = dir.join("y.qmcflac"); std::fs::write(&qmc, vec![0x22u8; 4096]).unwrap(); assert_eq!(scan::route(&qmc), Some(Engine::Qmc)); // 普通音频文件不应被认领 let mp3 = dir.join("z.mp3"); std::fs::write(&mp3, vec![0x44u8; 4096]).unwrap(); assert_eq!(scan::route(&mp3), None); let _ = std::fs::remove_dir_all(&dir); } #[test] fn task_registry_register_cancel_finish() { let tasks = DecryptTasks::new(); let flag = tasks.register("t1"); assert!(!flag.load(Ordering::SeqCst)); // 取消命中 assert!(tasks.cancel("t1")); assert!(flag.load(Ordering::SeqCst)); // 未登记的任务取消不报错、返回 false assert!(!tasks.cancel("nope")); tasks.finish("t1"); assert!(!tasks.cancel("t1"), "已结束的任务不应再被取消"); } }