From 6242a5eaabe9ebddd308f5733e26466c57cd9348 Mon Sep 17 00:00:00 2001
From: Warren <warren@momentry.ddns.net>
Date: Sun, 21 Jun 2026 20:52:31 +0800
Subject: [PATCH] P1: AsyncVfsBackend trait design (Phase 1 - framework)

- Add AsyncVfsBackend + AsyncVfsFile trait definitions
- Use cfg(feature = "async-vfs") for optional compilation
- Design notes for Phase 2-5 implementation
- Estimated: ~13 hours (multi-day project)

Phase 2: AsyncLocalFs (tokio::fs)
Phase 3: AsyncS3Vfs (async client)
Phase 4: AsyncSmbVfs (async wrapper)
Phase 5: WebDAV integration

Tests: 289 passed, 0 failed
---
 markbase-core/Cargo.toml     |  1 +
 markbase-core/src/vfs/mod.rs | 66 ++++++++++++++++++++++++++++++++++++
 2 files changed, 67 insertions(+)

diff --git a/markbase-core/Cargo.toml b/markbase-core/Cargo.toml
index 32934cf..aaef5b8 100644
--- a/markbase-core/Cargo.toml
+++ b/markbase-core/Cargo.toml
@@ -85,6 +85,7 @@ tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
 default = []                          # 默认不启用可选格式
 optional-formats = ["unrar", "xz2", "sevenz-rust"]  # 争议格式可选启用
 smb-server = ["dep:smb-server"]       # SMB server feature flag
+async-vfs = []                        # Async VfsBackend trait (Phase 1 - design only)
 
 [dev-dependencies]
 # tempfile moved to dependencies (needed for archive extraction)
diff --git a/markbase-core/src/vfs/mod.rs b/markbase-core/src/vfs/mod.rs
index 2a1da23..ae622a3 100644
--- a/markbase-core/src/vfs/mod.rs
+++ b/markbase-core/src/vfs/mod.rs
@@ -553,3 +553,69 @@ impl Default for VfsRaidConfig {
         }
     }
 }
+
+// ===== Async VfsBackend Design (Phase 1 - Framework) =====
+
+/// Async VFS 文件 trait（用于异步操作）
+/// 
+/// 设计要点：
+/// 1. 使用 `async fn` in traits (Rust 1.75+)
+/// 2. 所有方法返回 `Pin<Box<dyn Future>>`
+/// 3. 与 VfsFile 保持一致的接口
+#[cfg(feature = "async-vfs")]
+pub trait AsyncVfsFile: Send + Sync {
+    fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<usize, VfsError>> + Send + 'a>>;
+    fn write<'a>(&'a mut self, buf: &'a [u8]) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<usize, VfsError>> + Send + 'a>>;
+    fn seek<'a>(&'a mut self, pos: std::io::SeekFrom) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<u64, VfsError>> + Send + 'a>>;
+    fn flush(&mut self) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<(), VfsError>> + Send>>;
+}
+
+/// Async VFS 后端 trait（用于异步文件系统操作）
+/// 
+/// 设计要点：
+/// 1. 使用 `async fn` in traits (Rust 1.75+)
+/// 2. 所有方法返回 `Pin<Box<dyn Future>>`
+/// 3. 与 VfsBackend 保持一致的接口
+/// 4. 用于 WebDAV/SMB/SSH 异步处理
+#[cfg(feature = "async-vfs")]
+pub trait AsyncVfsBackend: Send + Sync {
+    fn clone_boxed(&self) -> Box<dyn AsyncVfsBackend>;
+    
+    fn read_dir<'a>(&'a self, path: &'a Path) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<Vec<VfsDirEntry>, VfsError>> + Send + 'a>>;
+    fn open_file<'a>(&'a self, path: &'a Path, flags: &'a open_flags::OpenFlags) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<Box<dyn AsyncVfsFile>, VfsError>> + Send + 'a>>;
+    fn stat<'a>(&'a self, path: &'a Path) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<VfsStat, VfsError>> + Send + 'a>>;
+    fn create_dir<'a>(&'a self, path: &'a Path, mode: u32) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<(), VfsError>> + Send + 'a>>;
+    fn remove_dir<'a>(&'a self, path: &'a Path) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<(), VfsError>> + Send + 'a>>;
+    fn remove_file<'a>(&'a self, path: &'a Path) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<(), VfsError>> + Send + 'a>>;
+    fn rename<'a>(&'a self, from: &'a Path, to: &'a Path) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<(), VfsError>> + Send + 'a>>;
+    fn exists<'a>(&'a self, path: &'a Path) -> std::pin::Pin<Box<dyn std::future::Future<Output = bool> + Send + 'a>>;
+}
+
+// ===== Async VfsBackend Implementation Notes =====
+//
+// Phase 2: AsyncLocalFs (tokio::fs)
+// - 使用 tokio::fs::File 替代 std::fs::File
+// - 使用 tokio::fs::read_dir 替代 std::fs::read_dir
+// - 使用 tokio::fs::create_dir 替代 std::fs::create_dir
+//
+// Phase 3: AsyncS3Vfs (ureq is blocking, need async client)
+// - 使用 async-s3 或 rusoto
+// - 或者使用 spawn_blocking 包装现有 ureq 调用
+//
+// Phase 4: AsyncSmbVfs
+// - smb-server crate 使用 async internally
+// - 需要 async wrapper
+//
+// Phase 5: WebDAV Integration
+// - VfsDavFs 改为 AsyncVfsBackend
+// - dav-server 已经是 async
+// - 直接使用 async 方法
+//
+// 预估工作量：
+// - AsyncVfsBackend trait: 1 hour
+// - AsyncLocalFs: 3 hours
+// - AsyncS3Vfs: 2 hours
+// - AsyncSmbVfs: 2 hours
+// - WebDAV integration: 3 hours
+// - Tests: 2 hours
+// Total: ~13 hours (multi-day project)