markbase/docs/fskit-research/ZFS_MVP_OPERATIONS.md

ZFS MVP FSKit Operations 清单 ⭐⭐⭐⭐⭐

Level 1: 基础挂载和读取（约200行）

必需实现（6个核心方法）

// 1. Volume激活 - 返回root item
func activate(options: FSTaskOptions) async throws -> FSItem {
    // 返回ZFS dataset的root目录
    return rootItem
}

// 2. 文件查找 - lookup文件/目录
func lookupItem(
    named name: FSFileName,
    inDirectory directory: FSItem
) async throws -> (FSItem, FSFileName) {
    // 调用libzfs查找文件
    // 返回找到的item和名称
}

// 3. 目录列举 - enumerate目录内容
func enumerateDirectory(
    _ directory: FSItem,
    startingAt cookie: FSDirectoryCookie,
    verifier: FSDirectoryVerifier,
    attributes: FSItem.GetAttributesRequest?,
    packer: FSDirectoryEntryPacker
) async throws -> FSDirectoryVerifier {
    // 调用libzfs列举目录
    // 使用packer添加每个item
}

// 4. 属性获取 - 获取文件属性
func attributes(_ item: FSItem) async throws -> FSItem.Attributes {
    // 调用libzfs获取属性
    // 返回Attributes对象
}

// 5. Volume同步 - 同步数据
func synchronize(flags: FSSynchronizeFlags) async throws {
    // 调用zfs sync
}

// 6. Volume停用 - 停用volume
func deactivate(options: FSDeactivateOptions = []) async throws {
    // 清理volume
}

---

Level 2: 基础写入（约100行）

必需实现（3个方法）

// 7. 文件创建 - 创建新文件/目录
func createItem(
    named name: FSFileName,
    type: FSItem.ItemType,
    inDirectory directory: FSItem,
    attributes: FSItem.SetAttributesRequest
) async throws -> (FSItem, FSFileName) {
    // 调用libzfs创建文件
}

// 8. 文件删除 - 删除文件/目录
func removeItem(
    _ item: FSItem,
    named name: FSFileName,
    fromDirectory directory: FSItem
) async throws {
    // 调用libzfs删除文件
}

// 9. Item回收 - 回收资源
func reclaimItem(_ item: FSItem) async throws {
    // 清理item资源
}

---

OpenClose + IO Operations（约50行）

// 10. 打开文件
func open(_ item: FSItem, options: FSTaskOptions) async throws -> FSFileHandle {
    // 返回file handle
}

// 11. 关闭文件
func close(_ handle: FSFileHandle) async throws {
    // 清理handle
}

// 12. 读取数据
func read(
    _ handle: FSFileHandle,
    buffer: UnsafeMutableRawBufferPointer,
    options: FSTaskOptions
) async throws -> Int {
    // 调用libzfs读取数据到buffer
}

// 13. 写入数据
func write(
    _ handle: FSFileHandle,
    buffer: UnsafeRawBufferPointer,
    options: FSTaskOptions
) async throws -> Int {
    // 调用libzfs写入buffer数据
}

---

延后实现（MVP不实现）

高级功能（8个方法）- Level 3+:

// 延后：符号链接
func readSymbolicLink(_ item: FSItem) async throws -> FSFileName
func createSymbolicLink(...) async throws -> (FSItem, FSFileName)

// 延后：硬链接
func createLink(...) async throws -> FSFileName

// 延后：重命名
func renameItem(...) async throws -> FSFileName

// 延后：扩展属性
func getXattr(...) async throws -> Data
func setXattr(...) async throws
func listXattrs(...) async throws -> [String]
func removeXattr(...) async throws

---

MVP Operations总清单

必需实现：约13个方法

• activate ✅
• lookupItem ✅
• enumerateDirectory ✅
• attributes ✅
• synchronize ✅
• deactivate ✅
• createItem ✅
• removeItem ✅
• reclaimItem ✅
• open ✅
• close ✅
• read ✅
• write ✅

延后实现：约8个方法

• readSymbolicLink ❌
• createSymbolicLink ❌
• createLink ❌
• renameItem ❌
• getXattr ❌
• setXattr ❌
• listXattrs ❌
• removeXattr ❌

总计：13个必需 + 8个延后 = 21个operations

---

MVP工作量细分

Level 1（6 methods）: 约150行

• activate (20行)
• lookupItem (30行)
• enumerateDirectory (40行)
• attributes (20行)
• synchronize (20行)
• deactivate (20行)

Level 2（3 methods）: 约80行

• createItem (30行)
• removeItem (30行)
• reclaimItem (20行)

OpenClose + IO（4 methods）: 约60行

• open (15行)
• close (15行)
• read (15行)
• write (15行)

总计：约290行 Swift + 约200行 C wrapper = 约490行

---